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.
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...
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.
Do not submit patches with commented-out code or code that is never reachable within
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 statusbut 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:
Open your fork on the GitHub web page select the branch from the drop-down and then push the “New Pull Request” button
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.
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 the ArduPilot Gitter channel
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!