The Three20 Branching Model

The Three20 branching model defines a set of paradigms used by the Core Team to ensure stable development on Three20. As a developer using Three20, you can be certain that any given release within this model is build-able and stable.

This article is split into multiple sections, with each subsequent section providing more in-depth discussions about the branching model.

Table of Contents

Getting Started

Three20 is a git-based framework. If you're new to git, check out the Git Community Book, Pro Git Book and Git Immersion. To focus your reading you should check out the following articles:

Primary Branches

There are two primary branches in Three20: master and development.

The master branch will be tagged with stable releases and should, in practice, be the only branch you use if you're simply using Three20 and not making any modifications. Each time a new release is made, you'll simply need to git fetch and then git rebase origin/master within the Three20 repository.

The development branch is for active development on the library and is not necessarily stable. All changes made to the library will first be added to the development branch and then merged into master on a release branch.

A release branch is a branch of development intended for a stable release. Each release branch will be named the same as its corresponding version and it subsequent tag name in the master branch. For example, at some point in the development branch we may decide to release 1.1.0. A new branch will be made from development with git checkout -b 1.1.0. This new release branch will then make any necessary final modifications to the library, such as bumping up the library's version number or writing release notes. Once the release branch is stable and ready to be released, it is merged into master.

Three20's branching model is based off of the one described at nvie.com.

Making Pull Requests

All changes that enter Three20 must be reviewed by at least one developer from the core team. In order to initiate a code review, you must create a GitHub Pull Request for your bug fix or feature request. The process to do this is rather straightforward.

Initial setup (one-time only)

Create a pull request

Add your fork to your local git Three20 repository:

~/three20 $ git remote add myusername git@github.com:myusername/three20.git

Once you're ready to have your code reviewed, push it to your fork.

~/three20 $ git push myusername ttcatalog-navfix

This will push your changes to GitHub. You can verify this by going to your fork on GitHub and checking that the new branch is available in the branches dropdown on your fork's homepage.

Now you're ready to make the pull request. Click the button. By default, GitHub will choose facebook/three20's master branch as the base branch, so you'll need to change this to the development branch. Make the base branch development and ensure that the head branch is the branch that you want to have reviewed.

Once you've selected the correct branches, ensure that you're sending the correct set of commits by selecting each of the tabs in the Pull Request form. Fill out the discussion form and try to give a detailed description about the problem, how you're attempting to fix it, and how the fix can be verified.

After sending the pull request, the members of the core team will be notified and begin the code review process. Good luck!

blog comments powered by Disqus