Skip to main content

Using Git and GitHub

This page describes the way we work with Git on the RabbitMQ project.

Overview​

Git is a fast, powerful distributed source control management system. It has numerous tutorials.

Team RabbitMQ uses Git to manage almost all of our source code.

RabbitMQ source code repositories are hosted on GitHub. Individual project pages on this website will generally point you in the direction of the specific combinations of modules you'll need to check out.

This website is open source and hosted on GitHub as well.

Branching policy: Branch per issue​

RabbitMQ uses the technique of branch per issue when developing RabbitMQ code, where each feature or bug fix is developed on a branch of its own using

git checkout -b

and merged into the main or stable branches only when it passes QA. Branches follow the pattern repository-name-NN, where repository-name is the name of the GitHub project where the issue was filed (eg. rabbitmq-dotnet-client) and NN is the GitHub issue number. The purpose of prepending the repository owning the issue is that an issue may require changes to several projects. There are also branches named bugNNNNN for issues in the original Bugzilla tracker (which is not public).

Pull Requests and the Review/QA Process​

Branches that are ready to be reviewed and/or QA'ed should be submitted as pull requests. Feedback is then given in the comments. After receiving feedback, update the original branch and push it: GitHub will take care of updating the pull request. Then the process goes on until the pull request is merged or closed (e.g. because a feature is rejected after an attempt to implement it).

The pull request must be made against the stable branch if it is a bugfix involving no incompatible changes with the latest stable release (ie. no changes to the Mnesia schema or the inter-node communication), or the main branch for everything else.

The main branch​

The default repository branch contains all the work that has been QA'd so far that is scheduled to appear in the next feature release.

Generally, you can track QA'd development work by tracking the main (default) branches of the RabbitMQ repositories of interest.

Pull requests that are meant to ship in currently maintained release series, for example, 3.11.x, are backported to release series-specific branches.

Release series branches​

There is also a separate branch for every release series that is currently maintained. These branches are named after the series: v3.12.x, v3.11.x, and so on.

It plays the same role as the main branch except that it carries merged, QA'd code intended for the next bug-fix release rather than the next general release.

Pull requests that are meant to ship in currently maintained release series are backported to these branches after being merged into the main branch. In the process they are labelled with backport-v3.12.x, backport-v3.11.x, and similar labels on GitHub.

For example, if a pull request is labelled with backport-v3.12.x, it means that it was backported, or at least considered for backporting, to the v3.12.x branch to ship in a 3.12.x release.

Tags​

Team RabbitMQ uses tags in the git repository to give names to snapshots of the state of the code: mostly importantly, releases. Generally, both the core repositories and the repositories of plugins intended to work with the named snapshot are tagged.

For example, if you are using RabbitMQ server version 3.12.7, then examining the output of git tag yields:

git tag
# omitted for brevity
# => v3.11.3
# => v3.11.4
# => v3.11.5
git checkout v3.11.5

At this point, you could proceed with compiling the plugin as explained in the plugin's documentation.