Difference between revisions of "Submitting patches"

Latest revision as of 12:43, 17 September 2014

Working on a feature or bug fix? Great! This page tells you all you need to know to submit your patch.

Git

First of all, these days development of collectd is organized on Github. If you don't have an account there already, we recomend you create one. It's free :-)

From a Github repository

Of course the first step is "cloning" collectd's Git repository: Go to https://github.com/collectd/collectd and click on the "Fork" button. You then pull this repository to your workstation:

git clone git@github.com/{your_user}/collectd.git

After you've made your changes and pushed them to Github, go to your copy of the collectd repository on the Github website and create a Pull Request (PR) from there.

Git without Github

Of course, you don't have to use Github. You can clone the repository anonymously via:

git clone git://github.com/collectd/collectd.git

After you made your changes you can send them in using the normal git-format-patch(1) and git-send-email(1) procedure. Please send them directly to collectd's mailing list at list@collectd.org. Mails sent by non-subscribers will be held for approval which will typically happen within 24 hours.

Please note that many team members rely heavily on Github's issue and PR tracker and it may take a while until somebody looks at a patch from the mailing list.

Documentation

If you're new to Git you might want to read the following documents to get started:

• The official Git tutorial
• Everyday GIT With 20 Commands Or So

Patching a certain branch

It's possible that you're asked to make your changes against a certain branch of the repository. To do this, you need to first fetch the branch into your local copy of the repository (here the local branch has the name "foo/branch-origin"):

git fetch origin foo/branch:foo/branch-origin

Then you create a copy of that branch (here it's named "foo/branch"), to which you will make your changes:

git checkout -b foo/branch foo/branch-origin

After making your changes to the "foo/branch"-branch you will need to create a (set of) patch(es) and send them in:

git format-patch -o output-directory -s foo/branch-origin..foo/branch
git send-email --to collectd@verplant.org output-directory

Patching a tarball

If you don't want to work out the complexities of Git (or you read this page after you made the changes ;) you can take some release (at best the latest one) and make your changes there.

I'll outline the typical steps one does when making the changes:

# Get the tarball
wget http://collectd.org/files/collectd-version.tar.bz2

# Unpack and rename the sources
tar jxf collectd-version.tar.bz2
cp -r collectd-version collectd-version-mine

# Do changes to collectd-version-mine

# Create the patch
diff -pur collectd-version collectd-version-mine >collectd-version-mine.patch

So the steps are typically:

• Download the latest release.
• Extract the source code and make a copy of the entire directory.
• Make your changes, a.k.a. *magic*.
• Test your changes.
• Do a make distclean to clean up the generated files.
• Generate the patch with diff -pur, as outlined above.
• Test if the .patch file applies cleanly.
• Review the .patch file.
• Submit the patch by sending an email to collectd's mailinglist at collectd@verplant.org. Mails sent by non-subscribers will be held for approval.

Other random notes

• If you patch a release, please don't submit changes to files such as Makefile, Makefile.in, configure and other files that are generated by the autotools. A (incomplete) list of uninteresting files can be found in the .gitignore file.
• Send one patch for each change in functionality. If they're too fine-grained it's easy to merge them together. The other way around is a pain in the back.
• Write code that blends in well (i.e. (try to) stick to the coding style). I won't be too picky about that, but keep it in mind please.
• Please don't compress your patches in any way. If the moderation filter holds back your mail because it's too big, please be patient: Unless it's huge I'll let it through. If I don't seem to take any action please drop me a note: There's quite some spam in the moderation filter, so I may have missed your mail.
• While 99.9 % of the code is just plain ASCII, there are situations in which you need non-ASCII characters, such as adding your name to the copyright notice at the top of each file, to the AUTHORS file or to the ChangeLog file. In this case, please make sure that the character set used is UTF-8. At the same time: Please write your name as it is supposed to be written, not some ASCII approximation of it – we consider this to be more polite.