Pull requests are used to contribute code and documentation changes to ROS projects. This article explains how to prepare and create a pull request from your fork of a ROS repository. With this information, you'll be able to submit focused changes in a pull request, ready for review.
Area: community | Content-type: how-to | Experience: beginner, intermediate, expert
Table of Contents
Pull requests (PRs) are proposals to merge your changes into a ROS project. Making a pull request allows you to collaborate with other ROS contributors, providing a space to discuss and review your code changes before a ROS maintainer merges them. Pull requests are welcome for any of the ROS repositories.
For more information about contribution etiquette, see :doc:`Contributing <../../Contributing>`.
- Create a fork of the target ROS repository for your code changes.
- Complete your code changes on a development branch, in your fork of the target ROS repository.
- Make sure your changes comply with ROS guidelines.
- If your pull request is for a code change:
- Make sure you've followed the guidance in the :doc:`Developer guide <../Developer-Guide>`.
- Check that your code complies with the relevant section of the :doc:`Code style guide </The-ROS2-Project/Contributing/Code-Style-Language-Versions>`.
- Make sure you've :ref:`run the tests <colcon-run-the-tests>` and the appropriate linter for your code changes.
- If your pull request is for a documentation change:
- Make sure you've followed the guidance in :doc:`../Contributing-To-ROS-2-Documentation`.
- If your pull request is for a code change:
Use the following guidelines to prepare your pull request:
- Scope and focus
- Limit each pull request to a single, well defined change.
- Submit unrelated changes as separate pull requests.
- Keep patches small and avoid unnecessary or incidental changes.
- Commit history and squashing
- Squash changes into a minimum number of clear, semantic commits to preserve a readable project history.
- Don't squash commits while a pull request is under review, as reviewers may not notice changes which can lead to confusion.
- You can create new commits while a pull request is under review.
- Draft pull requests
- Use draft pull requests to request early feedback while work is in progress.
- Don't expect draft pull requests to be formally reviewed or merged until you have marked them as ready.
- If you want early feedback from a specific person on a draft pull request, mention them (using @) in the pull request description or in a comment.
- Mentions and references
- If your changes are based on a design document, mention the package owners who reviewed the design in the pull request description.
- If your pull request depends on another pull request, clearly reference the dependency in the pull request description.
- If your changes are planned to be released with a specific version of ROS, include that version of ROS in the pull request description.
- Documenting your code changes
- If your pull request is for code changes, ensure you propose any required documentation updates (including API documentation, feature documentation, and release notes) in another pull request.
Create a pull request from the branch containing your changes in your fork, to the rolling branch of the target ROS repository. You can create your pull request using the GitHub CLI, GitHub Desktop, or using other methods.
For more information about creating a pull request from a fork, see the GitHub documentation.
For more information about each of the available pull request methods, see the GitHub documentation.
Populate the pull request by completing the sections shown in the description template, including:
- Description: summarize your code changes and the related GitHub issue, highlighting any key points or areas of concern.
- Issue: include the ID of the GitHub issue fixed by your changes, in the format
Fixes #(issue). This ensures that this issue is automatically closed when the pull request is merged. - Generative AI: if this pull request was generated using Generative AI, specify the model and version (for example, GitHub Copilot v3.2).
- Additional information: provide any context or details you think will be useful for understanding your changes.
After you've submitted your pull request, other developers and contributors in the ROS community will :doc:`review your changes <Reviewing-a-PR>`, including checking against the relevant guidelines.
When another developer or contributor adds a review comment or suggestion to your pull request, you receive a notification from GitHub.
You can view and discuss review comments directly in GitHub, and add further commits to your branch to address them when needed. You can also directly accept any suggested changes in the pull request, which adds a new commit to your branch automatically.
Discuss and iterate on your changes with this feedback, amending and updating your development branch with new commits as needed. Aim to reply back to review comments within one week, so that you and the reviewers do not lose the context of your changes.
After you've actioned any feedback, your pull request must be approved by a core maintainer for the target ROS repository before it can be merged.
When the core maintainer approves your pull request, they merge it to the target branch, and you receive a notification from GitHub.