Contributing to a ØMQ project

How We Work Together

Git and Github

The ØMQ Community uses the git version control system, and the GitHub cloud for its repositories.

The ØMQ Community consists of a number of projects, each with its own public git repository, or "git". Each git has an owner or owners (with admin rights), contributors (with read/write rights), and users (with read access). Each project organizes its git as it wishes. A project is "official" when it is held under the zeromq organisation at GitHub, otherwise it is "unofficial". To make your project "official", discuss on the mailing list. The zeromq organisation owners group have the privileges to create new projects.

We use github's "Fork + Pull Model" for changes. To make a change you fork the git in question, make and test your changes, and then make a pull request. The benefit of a pull request is that it is trackable, like an issue. Pull requests only work from a fork back to the original project.

You will need a free github account to work with us. We have no hard opinion on github except that we rather like it and it seems to encourage people to work together. The process is independent of github and we could switch in the future.

At all times, remember that it's up to you, as contributor, to convince others that your work is worth including. This means: make it useful, neat, test it fully, discuss it upfront, and so on.

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 (using the ØMQ source git as example):

$ git clone git://github.com/zeromq/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 <branchname> <remotename>', usually 'git push master origin'.

To pull a branch from a remote: 'git pull master origin', 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 master remotename'. 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 CONTRIBUTORS 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.

Contributing to libzmq

Since January 2012 libzmq has a new contribution process adapted from other successful ZeroMQ commmunities such as PyZMQ.

The goals of this process are to:

To remove all barriers to new contributors to libzmq, so that we allow more people to become core contributors to libzmq.
To allow anyone with process discipline to become a maintainer of libzmq without requiring knowledge of the codebase.
To encourage safe experimentation and learning without risk to stable versions and existing users.
To reduce the number of github repositories we use, without making libzmq more complex internally.
To reduce the risk of human error or negligence in the delivery of packages to end users.

Philosophy

All contributors to libzmq are equal; we all own the code and we all have equal rights to make patches.
The economics of any patch (its relevance, accuracy, and value) are decided by end-users, not by other contributors, nor by the maintainers.
The maintainers may have an opinion on the quality of the patch, see below.
Contributors experiment in their own repositories and contribute patches back to libzmq when they wish to.
The team that manages patches back to libzmq are the "maintainers". Maintainers are not developers and they have no opinion on patches; their job is to enforce process.
Our opinion on patches is that a bad patch is better than no patch: it encourages discussion, stimulates growth of the community, and offers a beginner a way to improve.
We also believe in getting minimal changes rapidly to real users, and encouraging organic improvement through small steps, rather than making large, dramatic, and stressful changes.
If you want an analogy for the Maintainer role, think of Wikipedia. We enforce process, stop outright spam and abuse, but allow others to argue value.
For a comparison with other development processes, see this article.

Patch Quality

Maintainers may reject patches or ask for improvements based on objective quality criteria. These are:

How clearly the patch is explained and how far it is anchored on previous discussion on zeromq-dev. Patches that come from nowhere and are not lucidly explained risk being rejected.
Whether the author of the patch is using his real name in his github account, or not.

Any contributor with opinions on the quality of a patch is encouraged to express them via further patches.

Guidelines

Patch authors SHOULD update NEWS if their patch fixes a bug or adds functionality. All changes to NEWS should be consistent with previous style. This maintainer strongly suggests the style from ZeroMQ/2.1.

Patch authors SHOULD NOT modify the libzmq version number. This is a maintainer decision.

A patch MUST adhere to the ZeroMQ Coding Style Guidelines.

Patches SHOULD NOT include substantial code from other projects, for several reasons. First, it can create licensing difficulties. Second, it creates bundled dependencies that are troublesome to keep accurate over time. Third, it creates risk for ZeroMQ since foreign code lives outside our community. Exceptions are code that you can cleanly rewrite and take ownership of.

How it Works

The master branch of libzmq holds the latest bleeding edge version and is always assumed to build though it will always be considered "unstable".

Releases are given their own branches using major-minor names ("3-1", "3-2"). Each release branch will progress through unstable to stable, and then legacy, with tags for each formal release.

Anyone who wishes to make a patch to libzmq forks the repository and works on their private copy. When they are ready to contribute their patch they make a github pull request.

All direct commits to libzmq are forbidden, no exceptions.

The maintainers will aggressively and optimistically merge pull requests back to libzmq master, with minimal opinion on quality and relevance. The only hard requirement is that the patch can be automatically merged.

Patches on stable releases will only be accepted for bug fixes, and require reproducible test cases. The maintainers will use these test cases to ensure that patches work.

Experimental and raw work exists as unofficial personal forks of libzmq that maintainers (and the community) have no opinion on, do not attempt to document, or manage.

If the maintainers do have any quality opinions on patches to master, it is that small patches are preferred over large ones. Any patch that seems oversized may be rejected on that basis alone.

All pull requests are echoed to the zeromq-dev list and discussions of the patch will happen on the list and/or the github pull request as people like. Note: this is not yet working, so please email zeromq-dev with news of your pull request.

Anyone who is discontent with a patch will make their own patch to fix or reverse the previous patch. Again, maintainers have no opinion on this.

To Add a New Feature

To contribute a new feature, one forks libzmq, writes and tests a minimal implementation of the new feature and makes a pull request. All pull requests are automatically published to zeromq-dev for review and comment. The maintainers at their discretion merge the pull request onto master. From then on, it will be included in automatic builds and tested by early adopters. When a minimal implementation gets consensus approval, one improves and extends it, and documents it.

How Releases are Made

Maintainers make releases in response to the flow of changes from the community. In general these rules of thumb apply:

A formal unstable release (off master) is the main way of getting important new functionality to users, who often will not trust git master branches. So, the maintainers will make unstable packages in order to drive speculative testing of new features by real users. The right moment to make an unstable release is when a series of edits (patches) have slowed down and started to stabilize.

When a branch is released as unstable, the maintainers may decide to create a formal major-minor branch. They may also keep some iterations on master. If they create a branch, they will need to merge commits to master to that branch. The advantage is that other changes can be continued independently of the branch.

A major-minor branch becomes naturally more stable as issues are solved, and maintainers will use change frequency to decide how to push such a branch through from beta to stable, and finally to legacy.

To Fix a Bug in a Stable Release

To contribute a bug fix, one forks libzmq, writes and tests the bug fix, and makes a pull request to master. The maintainers check that there is a proper test case (for fixes to stable branches) and retest the fix after merging the pull request. The maintainers then merge that fix to the various branches it affects, and the bug fix is then included in automatic builds of that branch and will go into new packages. The maintainers will treat bug fixes that cannot be tested with extreme skepticism.