Revision as of 03:35, 4 April 2010

Overview of the GIt Developer Workflows

Part way into the preparation of this documentation we stumbled upon an article just written that precisely describes the workflows that we will be embracing. Please read the below article before returning to this documentation.

http://nvie.com/git-model[1]

Many terms found in the article are used in the below documentation such as develop, feature and hotfix branches. Please refer back to the above if you need further clarification on such terms.

Different Branches of the Development and Release Cycle

With a project as large as SWG:ANH, both in terms of developers and in lines of code, it's important to keep a tight reign on the quality of code that makes it to end users. With that in mind the decision was made to adopt a 3-tiered approach to the development/release cycle. This ensures that the master branch is always stable and also gives developers freedom to explore new concepts and ideas without worrying about interrupting the work of others. Finally, it promotes better quality code due to the increased awareness of what other developers are doing and the pooling of the combined knowledge of the development team.

Milestones and Releases

In order for a development project to move forward it has to have something to move forward to, some goal that is the driving force for the developer efforts. The overall goal here at SWG:ANH is to reproduce a functional Star Wars Galaxies PreCU server, this is referred to as the Project Goal. This is quite a large goal though, certainly not one you'd sit down on a sunday afternoon and hope to complete. Without some way to measure progress developers quickly become disinterested causing the project to stagnate, this is not a good thing.

Dealing with the scope of the Project Goal involves breaking it down into a series of smaller goals, called Milestones. These Milestones serve as a stepping stones from where the project is currently to achieving the Project Goal. They consist of planned feature implementations and fixing known bugs. Once the goals for a particular milestone have been met a Release is made. Each release is tagged with a release number in the form of:

MAJOR RELEASE.MINOR RELEASE.PATCH RELEASE.BUILD NUMBER

What does this number mean though?

MAJOR RELEASE

This part of the build number only increases when the Project Goal is met. Our first Major Release will be the 1.0.0 release.

MINOR RELEASE

Every time a milestone is met the minor release number is increased. At the time of this writing the next minor release will be the 0.2.0 release.

PATCH RELEASE

In between milestones it's likely that there will be bugs found with the previous milestone. Each time a bug is identified, fixed and accepted into a release a Patch Release is created and this number incremented.

BUILD NUMBER

This number is tracked by our internal build server and is incremented each time the code is checked out and built. This number is used internally by QA to keep track of what features and fixes they should be testing at any given time, much like what SVN revision numbers were previously used for.

Tiers of Development

Feature Branches

All development for the project takes place in feature branches, whether it's a new feature or a bug fix. With Git, creating a branch is a simple and lightweight task and switching between various branches is even easier. For an example of the normal developer workflow see the "Use Case: Fixing a bug from manitis" section later in this guide.

Once work has been completed on a feature or a bug has been fixed the changes must be reviewed by at least one other developer on the team. This helps catch mistakes or issues that might not have been apparent to the original developer or perhaps a fresh set of eyes can point out a better path to take. Performing peer reviews also helps everyone to think about problems in new ways and to explore new ideas or solutions they might not have come up with on their own.

After passing peer review the changes are merged into the develop branch where they can be tested by QA.

Release Branches

Every release is the culmination of all the goals that make up a particular milestone. When QA has signed off on all the added features and bug fixes planned for a milestone a release number is picked and a new release branch is created off of the develop branch, this marks the beginning of the release cycle. Each release cycle begins with the beta phase, a period of testing of the planned features and fixes of a milestone. As soon as all bugs from testing are resolved it enters the RC phase, as long as no critical bugs are found at this point for a a 2 week period the code is determined ready for release. If any critical bugs are found a new RC is marked and the 2 week incubation period restarts.

Stable (master) Branch

On git the default branch is called the "master" branch. At SWG:ANH this is concidered the Stable branch and it is always the same as the current point-release of the project (@note at the time of this writing we haven't had our first release yet).

After a release branch has passed through it's RC phase of testing it is the Release Manager's duty to merge the release branch into the stable branch and publish all release materials (for example, creating the latest source tarball or windows installer and uploading them to the release site). Once this is done a new release branch is created for development on the next milestone.

This means that only code that has been peer reviewed and signed off by QA ever makes it into the stable master branch, which is important considering this is the branch that will be used by most end users to keep their server's up-to-date with the latest releases.

Use Case: Fixing a bug from mantis

Now that we've covered a bit of the basic's lets look at a real world example of how this developer workflow works. To do that we'll take a look at one of the more common tasks around here, fixing a bug listed in mantis.

The first thing you'll want to do when beginning to tackle any new problem is to create a new branch. This is easily done by running the following code:

git checkout -b issue0001602 develop

This will create a new branch called issue0001602 which indicates that this is a bug fix for the issue with an id of 0001602 in mantis. To see a list of available branches run the git branch command:

Dantooine:mmoserver anhuser$ git branch
* issue0001602
  release0.2
  master

The * next to the branch name indicates the current active branch. To switch back to the develop branch run:

Dantooine:mmoserver anhuser$ git checkout develop
Switched to branch 'master'
Dantooine:mmoserver anhuser$ git branch
  issue0001602
  release0.2
* develop
  master

As you can see by the * indicator, the active branch is now the develop branch. You can switch to any other branch by replacing "develop" with the name of the branch you wish to select. That is all there is to creating and switching between branches.

Once you've made the changes to fix the issue you're working on you're ready to make them available for others to review. You can do this by pushing your branch up to the live server with following command:

git push origin issue0001602

After pushing the branch up head to IRC to find another developer around to help perform the peer review, or, if nobody is around update the mantis ticket that a fix has been created and is ready to be code reviewed by a developer. Be sure to supply the name of the branch you created for the fix. Once another developer has signed off on the code you will need to have a maintainer merge it into the develop branch which will get pushed to the test center for QA to review.