Using Git and GitHub

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

Git is a fast, powerful distributed source control management system.

We use Git on the RabbitMQ project to manage almost all of our source-code.

  • Git has numerous tutorials.
  • RabbitMQ's Git 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

We use 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 master 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 master branch for everything else.

The master branch

The master branch contains all the work that has been QA'd so far that is scheduled to appear in the next release. The master branch of each RabbitMQ repository is usually roughly in sync with the master branches of the others. Generally, you can track QA'd development work by tracking the master branches of the RabbitMQ repositories of interest.

Maintenance branch

There's a separate branch for maintenance work, stable. It plays the same role as the master branch except that it carries merged, QA'd code intended for the next bug-fix release rather than the next general release.

Tags

We also use tags to give names to snapshots of the state of the code. 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.4.4, then examining the output of git tag in a copy of rabbitmq-stomp gives:

$ git tag
# omitted for brevity
rabbitmq_v3_3_5
rabbitmq_v3_4_0
rabbitmq_v3_4_1
rabbitmq_v3_4_2
rabbitmq_v3_4_3
rabbitmq_v3_4_4
        

It's important to make sure that all the repositories you are using are on the same tag as each other. Continuing with our example of server version 3.4.4, you could make sure your checkout of rabbitmq-stomp was at the rabbitmq_v3_4_4 tag by using git checkout:

git checkout rabbitmq_v3_4_4

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