Because it is used by software developers, Buildbot tends to receive a significant number of patches. The most effective way to make sure your patch gets noticed and merged is to submit it via GitHub. This assumes some familiarity with git, but not too much. Note that GitHub has some great Git guides to get you started.
- Patches should be based on the latest development code, not on the most recent release.
- Patches should include code changes, relevant documentation changes, and relevant unit tests. Any patch longer than a few lines which does not have documentation or tests will probably be rejected with a request to add documentation or tests. The are, of course, exceptions.
- Individual patches should, to the extent possible, be single-purpose. Please do not lump all of the changes you made to get Buildbot working the way you like into a single patch!
- Patches must reliably pass all tests. Buildbot does not tolerate "flaky" tests. If you have trouble with tests that fail without any of your changes applied, get in touch with the developers for help.
- Patches should pass pyflakes - most often pyflakes failures are unused imports, which are easy to clean up.
- Patches should pass pylint --rcfile common/pylintrc buildbot buildslave. Pylint takes a while longer to run, and is much more thorough than pyflakes.
- Python code in Buildbot uses four-space indentations, with no tabs. Lines should be wrapped before the 80th column.
- Patches that add features or change existing behavior should include a brief description in master/docs/relnotes/index.rst. You can reference bug numbers with :bb:bug:`1234` and pull reqests with :bb:pull:`233`.
- Git commit messages form the "ChangeLog" for Buildbot, and as such should be as descriptive as possible. Where a bug from this site (buildbot.net) is involved, mention the bug number, e.g., "(fixes #123)" or "(refs #456)". If you're submitting a patch without using Git, please be sure to include a commit message and your name and email, so the committers can construct a proper message.
The Buildbot developers are quite busy, and it can take a while to review a patch. While the following are not required, they will make things easier for the developers:
- Backward and forward compatibility is important to Buildbot. Try to minimize the effect of your patch on existing users.
- Make a distinct pull request, on a distinct branch in your repository, for each unrelated patch - some patches may get merged immediately, while others will require revision, and this can get very confusing in a single branch.
- Smaller, incremental patches are better than one large patch, as they can be considered on their own merits. It's OK for a patch to add code that is unused (except for tests, of course!) until a subsequent patch is applied.
- Git history is the primary means by which Buildbot establishes authorship. Be careful to credit others for their work, if you include it in your code.
How to create a patch
(Note that this github guide offers a more generic description of this process)
- Sign up for a free account at http://github.com, if you don't already have one.
- go to http://github.com/buildbot/buildbot and click “fork”. This will create your own public copy of the latest buildbot source
- clone your forked repository on your local machine, so you can do your hacking. GitHub will display a link titled "Your Clone URL". Click this link to see instructions for cloning your URL. It's something like
git clone email@example.com:myusername/buildbot.git cd buildbot
- locally, create a new branch based on the master branch
git checkout -b myfixes origin/master
- hack mercilessly. If you're a git afficionado, you can make a neat and pretty patch sequence; otherwise, just get it done. Don't forget to add new test cases and any necessary documentation!
- just to be safe, test your changes:
git add $files_that_matter git commit
- See the Patch Guidelines section, below, for a description of what the patch should include, and how the commit message should be written.
- When you're confident that everything is as it should be, push your changes back to your repository on GitHub, effectively making them public.
git push origin myfixes
- Now all that's left is to let the Buildbot developers know that you have patches awaiting their attention. In your web browser, go to your repository (you may have to hit "reload") and choose your new branch from the "all branches" menu.
- Double-check that you're on your branch, and not on a particular commit. The current URL should end in the name of your patch, not in a SHA1 hash.
- Click “Pull Request”
- Double-check that the base branch is "buildbot/buildbot@master". If your repository is a fork of the buildbot/buildbot repository, this should already be the case.
- Fill out the details and send away!
One of the buildbot developers will look at your changes and either merge them or offer comments and ask you to revise.