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, have a look at the linked Git guide below[1]. 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. The most relevant ones 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 fetch+merge them into the multitheftauto repository. See the guide (p.39) for more details[1].
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. This can also be advantageous when you're doing a lot of work that you want to split up in commits for maintainability.
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
- experimental (branch)
- 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 (at that point, we'll fork it into 1.x-Release). 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.
Stable stuff will nearly always be pulled in from known developer forks, which can be done by anyone who has write access to the main repository. Experimental stuff should not go in this branch.
Guidelines
Commits that are merged from a fork into master must be:
- reviewed by other developers
- tested for stability and correctness (if necessary, the commit can be merged 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
- merged from the originating fork into master
Experimental
The experimental branch will be based on master and will contain any changes that are unplanned or haven't been tested properly yet. We will provide experimental nightly builds for those who wish to test any experimental (non-stable) features. This branch will be kept in sync with the master branch by periodically fetching and merging the changes from master.
Experimental stuff can be pulled in from any fork (known or unknown developers), which can be done by anyone who has write access to the main repository. Stable stuff doesn't have to be merged in this branch as it is automatically pulled in from master (see above).
Nightly builds
As mentioned above, nightly builds will be available in two different flavours:
- stable (compiled from multitheftauto/multitheftauto/master
- unstable (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.