collectd
Homepage
Wiki

Navigation

Submitting patches

Using Git

The preferred way of submitting patches is using the Pull Request feature on Github. If you do not yet have an account there, please consider creating one – it's free of charge for free software projects. While preferred, we don't force you to create a Github account.

Using Github: Go to our Git repository on Github and click the Fork button. Afterwards, you will need to clone your repository / fork:

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

Without Github: Clone collectd's Git repository using the following command:

git clone git://git.verplant.org/collectd.git

After you cloned the repository you should create a development branch. If you want to implement a new feature, create the branch based on the master branch. If you are fixing a bug, base your branch on the oldest still supported version which includes this bug, e.g. the collectd-5.1 branch. We have a wiki article describing the repository structure in case you wonder what all this is about.

# Create a development branch for a new feature
git branch my_dev_branch master

# Create a development branch for a bugfix
git branch my_dev_branch collectd-5.1

After you have implemented your new feature or your bugfix, you will (hopefully) want to submit the changes to us. If you're using Github, open a Pull Request (PR). Otherwise, send the patch or patch series to the mailing list.

Using Github: Go to your fork of the repository and click on the Pull Request button. As head branch select your development branch, i.e. the branch holding the commits to be merged. For base branch, select either master if you were implementing a new feature or the appropriate version branch, e.g. collectd-5.1. This should, of course, match the branch you used above.

Without Github: Send your changes to the mailing list using the normal git-format-patch(1) and git-send-email(1) procedure. Please send them directly to collectd's mailinglist at . Mails sent by non-subscribers will be held for approval which will typically happen within a day or two.

# Assuming a new feature based on the "master" branch:
git format-patch -o output-directory -s master..my_dev_branch
git send-email --to collectd@verplant.org output-directory

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

Patching a release

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 . 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.