Submitting Patches Back to Master

Once you have a bug fix or new feature you would like to have included in the ArduPilot project you should submit a Pull Request. The main developers will see your changes in the Pulls list, review them and if all goes well they will be merged into master.

This page provides advice to make the process go smoothly.

Preparing commits

• Commits should be in a new branch of your fork/clone (i.e. not “master”). These should be done on a local branch and then pushed to your web-based fork of ArduPilot.

• The new branch should be up-to-date with ArduPilot/master and should not include any other changes.

• Commits should be small and do just one thing. If a change touches multiple libraries then there should be a separate commit per library, and a separate commit per vehicle directory. This is true even if it means that intermediate commits break the build.

• Well-written, concise comments are encouraged.

  Commit messages should be of the form:

  Subsystem: brief description
  
  Longer description...
  

  Example:

  APM_Control: reduce the number of parameter saves in autotune
  
  do not save a parameter unless it has changed by 0.1%
  

• clean up your local commit history using interactive rebase (i.e. git rebase -i "HEAD~10") to re-arrange patches and fold things together. The idea is to present a logical set of patches for review. It can take a bit of effort to get used to interactive rebase, but it is definitely worth learning. Refer to online resources to understand how to use this tool.

• Each commit should involve only a single library. The commits of the changes in each library should be squashed (see Interactive Rebase: cleaning up commits) into the minimal number of commits per library that allows readability and clarity when reviewing (usually only one commit). The “Tools/gittools/git-subsystems-split” script can be run on any commit spanning multiple libraries to create a single commit for each library module affected before submitting. if needed.

• Do not submit patches with commented-out code or code that is never reachable within #define s.

• Try to follow the style guide so your code fits in with the existing code. In particular, ensure your editor uses 4 spaces intead of tabs.

• Unix line endings (LF) are used. Git should take care of this automatically, but if you notice that you have a lot of files that show up as changed in git status but you didn’t touch those files, you may need to check to see if local git settings regarding line endings are correct.

• read your changes, doing your own review. The best way to do this is to use the “gitk” tool. Look over your own changes critically. Make sure they do not include anything you don’t want to go into the pull request. It is best to read your changes at least several hours after you wrote the code, and preferably the next day. Look over them carefully and look for any bugs.

• if you have access to a Linux build environment then build your modified tree using Tools/scripts/build_all.sh. That will test that all the builds for different boards and vehicle types work. If you don’t have a Linux build environment then please test the build for Pixhawk boards and rover, copter and plane if your changes may affect those vehicles.

• test your changes in SITL if possible. If you can’t run SITL then test your changes in a real vehicle.

Submitting a pull request

To submit a pull request on GitHub for review and possible inclusion in the official repository, follow these directions:

1. Open your fork on the GitHub web page select the branch from the drop-down and then push the “New Pull Request” button

   

2. Check the “base fork” is ArduPilot/ardupilot and “base” is “master” and then fill in the PR’s subject line and detailed description. The detailed description should include any evidence of testing performed.

   Check the list of changes at the bottom of the page only includes your intended changes, then push the “Create pull request” button.

   

Next Steps

You can track the state of your PR from the Pull Requests list.

PRs are more likely to be merged quickly if:

• The PR clearly states what changes in behaviour are expected

• Good testing evidence is provided. This could be graphs of logs recorded before and after the change

• The PR is discussed on the weekly dev call. To get the PR discussed add the “DevCallTopic” label. If you are unable to add the label ping one of the developers on ArduPilot Discord

It is very common, especially for large changes, for the core developers to ask you to modify the pull request to fit in better with the existing code base or resolve some knock-on impact that you may not have known about. Please don’t take this the wrong way, we’re definitely not trying to make your life difficult!