Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
80 lines (52 loc) · 3.67 KB

CONTRIBUTING.md

File metadata and controls

80 lines (52 loc) · 3.67 KB

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 Gazebo 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 Gazebo release. 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 Gazebo release's images are built for.

The gazebo folder

The gazebo folder has an Earthfile used to create images with Gazebo installed from debian packages. The Gazebo definitions follow the installation instructions from packages.osrfoundation.org.

  • gazebo/Earthfile defines a target for each active Gazebo release. Each target creates OCI images with different levels of Gazebo installation: core, base, and full.

If you think there should be a new image variant in gazebo (ex: a development image with additional tools), please create an issue on this repository to discuss it.

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 Gazebo release. Inside it is another hardcoded copy of the knowledge of what architectures are supported by each Gazebo release. 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 Gazebo release'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-gazebo-release.yaml pulls all images for a given Gazebo release and makes sure the gz sim command can be used.
  • build-one-ros-distro.yaml builds all images for a given Gazebo release, pushes them to github actions, and then calls test-deployed-images-one-gazebo-release.yaml to make sure they work.
  • build-one-ros-distro-if-necessary.yaml checks if a new version of the gz-$release package is available, and if so calls build-one-ros-distro.yaml to update it.
  • Various release-specific build workflows run once per week and rebuild all of the Gazebo images.
  • ci-python-lint.yaml runs the black Python linter.