Git Coding Guidelines

This page is to discuss a new set of coding guidelines that will be used for the rest of the development phase through Git and GitHub. It also covers related aspects of the development process such as nightly builds.

Before you start reading, ask for a link to the Git guide. It does a pretty good job of explaining how Git works.

Why Git?

Git has several advantages compared to our current source code management system Subversion. Some relevant features are outlined below.

Forks and patches

One of the differences of Git is that it is distributed. That is, everyone owns his/her own repository that is forked from our main repository multitheftauto/multitheftauto, and all the changes that one would normally commit to the SVN trunk (or branch) are kept in that forked repository.

The advantage of this approach is that any programmer in the world that is registered at GitHub is capable of forking the multitheftauto repository and work on their own changes. All forks based on multitheftauto will show up on the Networks page at GitHub, so it'll be easy to track. No need to mess around with patches: if we see someone doing good work, whether it be a known or unknown developer, it's just a matter of reviewing the commits (comments can be posted for every commit, in every file, on every line) and pull (fetch & merge) them into the multitheftauto repository. See the guide (p.39) for more details.

Offline commits

Another feature of Git is that you don't need an internet connection in order to commit. You can commit as much as you want to your local (off-line) repository, and just push all of these when you feel like it. Obviously, this benefits the speed at which you commit as there's no need to send any data to the remote repository. This can also be advantageous when you're doing a lot of work that you want to split up in commits for maintainability and push in one go.

Synchronization with SVN

Git is fully compatible with our current SVN repository. This means that any changes that are made in git repositories can be committed to the SVN repository, and any changes that are made in the SVN repository can be fetched into the git repository. As far as migration goes, this is pretty valuable as we will be able to work side-to-side with SVN and git while people are switching over.

Master, experimental, trunks and branches

The main repository multitheftauto/multitheftauto will be set up with write access for all current project contributors and owners. The repository is structed as follows:

• master
• untested
• merge
• experimental
• 1.0-Release (tag)

Master

The master is the default (top) branch that will contain the stable version that will ultimately form the next release.. and nothing more than that. On release, it will be forked into 1.x-Release and the entire cycle starts over again. In order to keep the master stable, we will only merge the changes in that are planned and outlined in the Roadmap. Nightly builds will be available for anyone who wishes to test and use the stable version. Nothing should get into this master branch without having been thoroughly tested. This branch should remain as stable as a release build.

Untested

Code is merged into the untested branch periodically, perhaps every few days, or maybe weekly. Once the code has been merged there, it will be built and tested (hopefully by automated tests at some point.) The job of doing this merge and test will be passed around in some fashion.

Merge

The merge branch is where code can be merged to at any point. This code should be intended for the release, so should be tested to the extent of your ability first! Experimental code that is more likely to break should go into the experimental branch.

Experimental

The experimental branch is for risky code or work-in-progress code that needs to be built by the build system so that it can be tested. Once it has been found to be stable, it can be merged up to merge from the original fork. Periodically this fork may be reset to being identical to merge, and will be kept in sync with merge. If necessary more experimental branches could be created if more than one experimental feature requires a build at once.

Your forks

You should generally fork either merge or experimental and work there, then merge up to the relevant branch when you're ready.

Guidelines

Commits that are merged from a fork into merge must be:

• reviewed by other developers
• tested for stability and correctness (if necessary, the commit can be pulled into experimental first for testing purposes)

Commits that have already been merged into experimental and were found to be stable must be:

• reviewed by other developers in the originating fork
• pulled from the originating fork into master

Nightly builds

As mentioned above, nightly builds will be available in two different flavours:

• stable (compiled from multitheftauto/multitheftauto/master)
• untested (compiled from multitheftauto/multitheftauto/untested)
• unstable (compiled from multitheftauto/multitheftauto/merge)
• experimental (compiled from multitheftauto/multitheftauto/experimental)

We will have to decide on the frequency of the (nightly) builds as these could be different for the two.