zeromq

How We Work Together

The ØMQ Community uses the C4 process (with some caveats) for its core projects: libzmq and stable releases (zeromq2-x, zeromq3-x) as well as surrounding projects. The main exception to C4 is that we still use Jira for issue tracking (to be fixed at some point).

If you contribute a nice patch and you have some GitHub reputation we'll invite you to join the Maintainer's team and you can add "ZeroMQ maintainer" to your resume or C.V.

Our process is this:

1. Log an issue that explains the problem you are solving.
2. Provide a test case unless absolutely impossible. In C is best, and in the issues repo is ideal.
3. If you're making a change to a stable version, we always need an issue and test case.
4. Make your change as a pull request (see below).
5. Discuss on the zeromq-dev mailing list as needed.
6. Close the issue when your pull request is merged and the test case passes.

Getting Started

Download and install git. On Linux, apt-get install git. If you're new to git, read the git docs, and Pro git by Scott Chacon.

Ensure that your copy of git is configured with your real name and the e-mail address you wish to be associated with your contributions. This is required to correctly track authorship:

$ git config --global user.name "Your Name"
$ git config --global user.email your.name@example.com

Create a user profile at GitHub with your real name and the same email you used to configure your git.

Configure your Bash prompt if you are on Linux by copying this into your .bashrc or .bash_profile.

Do your research. To contribute to a project, you need to know (a) the owner of that project and (b) the location of the git at github. If it's not obvious, ask on zeromq-dev.

Basic Techniques

If you're new to git, especially if you come from SVN, you work by getting full copies of the repository on your local hard disk, and then exchanging sets of changes to and from other gits. It sounds complex, and sometimes is, but it works very well for large loose groups like ours.

A git is a set of 'branches', starting with the 'master' branch. Use 'git branch' to see what branches you have.

To get a git onto your hard disk: use the 'git clone' command, e.g.:

$ git clone git://github.com/MyName/zeromq2.git

Behind a firewall you may need to use 'http:' instead of 'git:'.

Your clone has an origin, which is a 'remote' by that name. Use 'git remote -v' to see what remotes you have.

To make your changes: use your favorite tools to edit, compile, build, test. Do not allow your editor to reformat code you're not changing, or remove whitespaces elsewhere, this will make your patches useless.

To commit your work: use 'git add (files)' and 'git commit'. Use 'git commit —amend' to add to or fix up the previous commit.

The 'git commit' command opens an editor for you to enter a commit message. Provide a 1-line summary, followed by a blank line, followed by a description of what you changed. The commit message becomes part of the permanent history of the project if your changes are accepted, so be clear and concise. And check your sleppling.

To abandon your changes: either wipe your directory and re-clone the project git, or use the 'git reset' command. All git commands have help ('git reset —help'), and extensive explanation online.

To push a branch to a remote: 'git push <remotename> <branchname>', usually 'git push origin master'.

To pull a branch from a remote: 'git pull origin master', which fetches the master branch from the origin remote, and merges it into your local master branch.

The Pull Request Model

The home page for the project git has a button "Fork", which will fork the project into your own profile. Click it, and you get a fork of the project git. Clone your forked git to your hard disk. You can now work in your forked git.

The best strategy is to make each change (a set of commits) in its own branch. Your master branch can then track precisely the original repository master.

Work and commit your work as explained in Basic Techniques, and push your changed branches back to your forked repository. When you're ready to send your work to the project owner, go to github.com and click the "pull request" button. Do make one pull request for each set of changes that go together.

To resync your fork with the original repository, add a remote that points to that repo, and use 'git pull —rebase remotename master'. For example:

#  One time when you start working
git remote add libzmq git://github.com/zeromq/libzmq.git
#  Each time you need to resync
git pull --rebase libzmq master

Separate Your Changes

Separate different independent logical changes into separate commits (and thus separate patch submissions) when at all possible. This allows each change to be considered on it's own merits. Also, it is easier to review a batch of independent changes rather than one large patch.

Write Good Commit Messages

Commit messages become the public record of your changes, as such it's important that they be well-written. The basic format of git commit messages is:

• A single summary line. This should be short — no more than 70 characters or so, since it can be used as the e-mail subject when submitting your patch and also for generating patch file names by 'git format-patch'. If your change only touches a single file or subsystem you may wish to prefix the summary with the file or subsystem name.
• A blank line.
• A detailed description of your change. Where possible, write in the present tense, e.g. "Add assertions to zmq_foo()". If your changes have not resulted from previous discussion on the mailing list you may also wish to include brief rationale on your change. Your description should be formatted as plain text with each line not exceeding 80 characters.

Give Yourself Credit

Add yourself to the AUTHORS file or other lists of contributors for the project, with your commit. The maintainers won't do this, it's your choice whether you consider your patch worth a mention, or not.

You must make contributions under your real name, associated with your github account. Anonymous contributions may be made via proxies, ask on IRC if someone will help you.

Copyrights and Licenses

Make sure your contributions do not include code from projects with incompatible licenses. ZeroMQ uses the LGPLv3 with a static linking exception. If your code isn't compatible with this, it will sooner or later be spotted and removed. The best way to avoid any license issues is to write your own code.

Test Cases

For stable releases, patches (if they change the behavior of the code) must have issues, and test cases.