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.

Quick tutorial

For a quick tutorial on how to setup and use TortoiseGit, go to the How to use TortoiseGit wiki page on GitHub.

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
• merge
• untested
• 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. This is not the SVN trunk. 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.

Merge

The merge branch is the first stop for code that originates from a developer's fork and is intended for the release. All code should naturally be tested to the extent of the developer's own ability first. Experimental code that is more likely to break should go into the experimental branch instead.

The merge branch will be a collection/mess of untested changes that have been pulled in from forks by anyone with write access. The changes can be rapidly tested in the unstable build. This build is comparable to a nightly trunk build, which can be seriously broken at times.

Untested

The untested branch sits below merge and is intended to act as a barrier to master. By using this barrier, we can selectively choose sets of multiple (related) changes from merge that are considered to be complete. While merge may contain all sorts of unrelated pulled-in changes from various developers that are still only half working (due to programmer error), the untested branch will only pull these changes in when they're considered complete every few days. A build containing a specific set of changes is then generated and tested (ideally this would be automated at some point).

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 four different flavours:

• rc (release candidate, compiled from multitheftauto/multitheftauto/master), rarely built
• untested (compiled from multitheftauto/multitheftauto/untested), built on-change
• unstable (compiled from multitheftauto/multitheftauto/merge), frequently built
• experimental (compiled from multitheftauto/multitheftauto/experimental), built on-demand

For more information, head over to the Nightly Builds page.