Skip to content

Latest commit

 

History

History
159 lines (118 loc) · 6.75 KB

CONTRIBUTING.md

File metadata and controls

159 lines (118 loc) · 6.75 KB
Raw

Contribution Guide

Thank you for being willing to help!

How to make a Documentation Contribution

This repo uses Markdown for its documentation. These files have the extension .md. When adding to these files please put each sentence on its own line. This style makes it easier to review changes to the documentation.

# This is a title

Please put one sentence per line.
Yes, like this.
Thank you!

If you would like to add a tutorial, please consider contributing it to the official ROS 2 Documentation. If it's not accepted there, then please create an issue on this repository and we can work together to figure out where to put it.

How to make a source code contribution

Install the required versions of dependencies

Required to build images:

  • qemu-user-static version 6.2
  • buildah version 1.34.0

Required to test images:

  • podman Not sure what version, but both versions 3.4.4 and 4.9.0 have worked for me.

Required to lint source code:

  • black - any 2024 version.

The best way to get these dependencies is to use Ubuntu 22.04 (Jammy). First, install qemu-user-static via sudo apt install qemu-user-static. Second, build and install buildah from source.

There is a script to install the build dependencies: ./scripts/install_dependencies.bash

Understand How the repository is structured

Understanding where everything is will help you make a contribution.

At a high level, this repository uses Python scripts to invoke buildah to build images from Dockerfiles. The python script is called using Github Actions to build images for each active ROS distro. The images are pushed to Github Packages. Afterwards anyone can pull the image they need and run it.

What's in the ros1 and ros2 folders

The ros1 and ros2 folders hold Dockerfile definitions for ROS 1 and ROS 2 respectively.

ros1
├── desktop
│   └── Dockerfile
├── desktop-full
│   └── Dockerfile
├── perception
│   └── Dockerfile
├── robot
│   └── Dockerfile
├── ros-base
│   └── Dockerfile
├── ros-core
│   ├── Dockerfile
│   └── ros_entrypoint.sh
├── simulators
│   └── Dockerfile
└── viz
    └── Dockerfile

ros2
├── desktop
│   └── Dockerfile
├── desktop-full
│   └── Dockerfile
├── perception
│   └── Dockerfile
├── ros-base
│   └── Dockerfile
├── ros-core
│   ├── Dockerfile
│   └── ros_entrypoint.sh
└── simulation
    └── Dockerfile

Originally the files in ros1 were taken from here, and the ROS 2 definitions were taken from here. The files don't need to match the ones in osrf/docker_images exactly, but they should stay close.

In the ros1 folder each subfolder is named after a metapackage defined by REP 142. In the ros2 folder each subfolder is named after a variant defined by REP 2001. If you think there should be a new folder in ros2 (ex: a navigation image with Nav2, or a moveit2 image) then please propose a new variant to REP 2001 first as a pull request to the ros-infrastructure/rep repo. After it's accepted we can create an image for it here. If you think there should be a new ROS 1 image, I would suggest not creating one. ROS 1 is nearly end of life and should be kept stable.

What's in the scripts folder

The scripts folder holds Python and Bash scripts used for building and testing the images

scripts/
├── build_images.py
├── install_dependencies.bash
└── test_images.py

The file build_images.py invokes buildah to create all images for one ROS distro. Inside it is hardcoded knowledge of what architectures are supported by each ROS distro. It also has the option to push images to github packages. When pushing images, each image is built and then pushed one at a time to avoid rate limiting on pushing images. Run ./scripts/build_images.py --help to see what options it takes.

The file test_images.py invokes podman to run commands in all images for one ROS distro. Inside it is another hardcoded copy of the knowledge of what architectures are supported by each ROS distro. Run ./scripts/test_images.py --help to see what options it takes.

The install_dependencies.bash script installs the dependencies needed to build images on an Ubuntu 22.04 machine.

What's in the .github/workflows folder

This folder contains github workflows. These are used to build and test the images.

.github/workflows/
├── build-and-deploy-all-if-necessary.yaml
├── build-and-deploy-all.yaml
├── build-and-deploy-one-ros-distro-if-necessary.yaml
├── build-and-deploy-one-ros-distro.yaml
├── ci-build-amd64-image-one-ros-distro.yaml
├── ci-build-amd64-images.yaml
├── python-lint.yaml
└── test-deployed-images-one-ros-distro.yaml

The workflow test-deployed-images-one-ros-distro.yaml pulls all images for a given ROS distro and makes sure the ros2 command can be used.

The workflow build-and-deploy-one-ros-distro.yaml builds all images for a given ROS distro, pushes them to github actions, and then calls test-deployed-images-one-ros-distro.yaml to make sure they work.

The workflow build-and-deploy-one-ros-distro-if-necessary.yaml checks if a new version of the ros-$distro-desktop-full package is available, and if so calls build-and-deploy-one-ros-distro.yaml to update it.

The workflow build-and-deploy-all-yaml runs once per week and rebuilds all of the ROS images.

The workflow build-and-deploy-all-if-necessary.yaml runs every 6 hours and calls build-and-deploy-one-ros-distro-if-necessary.yaml for every supported ROS distro.

The workflow python-lint.yaml runs the black Python linter.

The workflow ci-build-amd64-image-one-ros-distro.yaml builds the amd64 architecture images for one ROS distro, and the workflow ci-build-amd64-images.yaml calls it for every supported ROS distro.