Skip to content

Latest commit

 

History

History
87 lines (59 loc) · 4.89 KB

CONTRIBUTING.md

File metadata and controls

87 lines (59 loc) · 4.89 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 dependencies

Install these to build and test images:

  • qemu-user-static version 6.2
  • docker not sure what version. 24.0.5 works.
  • earthly version 0.8

Install this to lint source code:

  • black - any 2024 version.

Repository Structure

This repo uses Earthly to build and push OCI images from Earthfiles. The Earthfiles create OCI Images for each active ROS distro. The Earthfiles push the images to Github Packages.

There is a top-level Earthfile which imports from Earthfiles in subfolders. The top-level Earthfile defines what platforms each ROS distro's images are built for.

The ros1 and ros2 folders

The ros1 and ros2 folders each have an Earthfile used to create images with ROS 1 and ROS 2 installed from debian packages, respectively. The ROS 1 images definitions were taken from here, and the ROS 2 definitions were taken from here. The Earthfiles don't need to match the Dockerfiles in osrf/docker_images, but they should stay close.

  • ros1/Earthfile defines a target for ROS Noetic calle noetic. That target builds an OCI image for each metapackage defined by REP 142 plus simulators-osrf.
  • ros2/Earthfile defines a target for each active ROS 2 distro. Each target creates an OCI image for each 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. If you think there should be a new ROS 1 image, I would suggest not creating one. ROS 1 is nearly end of life.

The apt folder

apt/Earthfile contains utilities for using the apt package manager in Earthfiles.

The scripts folder

The scripts folder holds miscellaneous scripts used by the github actions in this repository.

  • test_images.py invokes docker 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.
  • install_dependencies.bash installs qemu-user-static on an Ubuntu 22.04 machine.
  • is_new_version_available.py checks if there's a new verion of a debian package. This is used to determine when new images need to be built after a ROS distro's packages get sync'd to the main apt repo.

The .github/workflows folder

This folder contains github workflows that build and test the images.

  • test-deployed-images-one-ros-distro.yaml pulls all images for a given ROS distro and makes sure the ros2 command can be used.
  • 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.
  • 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.
  • build-and-deploy-all-yaml runs once per week and rebuilds all of the ROS images.
  • 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.
  • python-lint.yaml runs the black Python linter.
  • 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.