Below is a diagram and a description of the git branching model we use for RichFaces.  I describes how/when we use feature branches, and how we use branches for releases.

RichFaces Git Workflow Model

Branches in Detail

Development happens on either a feature branch, or the master branch.  When a new feature is complete (or has reached a significant milestone) it is merged into the master branch.

feature branches are created for work on introducing major new features and also for investigating fixes to non-trivial bugs.

release branches are created either from the master branch after a stabilization process or from a tag (for micro releases).

These release branches go through a release process, with release testing and stabilization.

Naming Conventions and Placing of Branches

release branches are named using the release version they are introducing:

release/5.1.0.Alpha1
release/5.1.1.CR1

Release branches live in the RichFaces project repository, they should be removed right after introducing the final tag to the repository.

feature branches are named using the issue that introduced them, along with a short descriptive name:

RF-11029-short-name

feature branches can be published to either personal Git repositories to the RichFaces Git repository depending on the level of collaboration required.

Issue Workflows

We have distinguishing two workflows based on role in the project:

• commiters acts as integration managers - have write access to project repositories
• contributors can't write into project repositories directly, but can open pull requests

Commiter Workflow

1. issue is assigned
2. create feature branch (for large features/fixes)
3. work on issue, commiting changes
4. rebase changes against master
5. push to master
6. resolve issue

First-Time Contributor - fork and clone the repositories

1. fork the repository on GitHub (using Fork button)
2. clone your repository locally (remember to change github_username)
   $ git clone git@github.com:github_username/richfaces.git
   
3. add upstream repository as an alternative remote
   $ git remote add upstream git://github.com/richfaces/richfaces.git
4. you should endup with two remote repositories setup:
   $ git remote -v
   

   upstream	git@github.com:richfaces/richfaces.git (fetch)
   upstream	git@github.com:richfaces/richfaces.git (push)
   origin	git@github.com:github_name/richfaces5.git (fetch)
   origin	git@github.com:github_name/richfaces5.git (push)

5. Proceed to the "Contributor Workflow"

Contributor Workflow

Assuming you have two remote repositories tracked (see above: First-Time Contributor, step 4):

$ git remote -v

The workflow consists of:

1. create an issue (when working on issue which doesn't exist yet) - e.g. RF-abc
2. fetch latest upstream
   $ git checkout master
   $ git pull --rebase upstream/master
3. create a feature branch
   $ git checkout -b RF-#####-some-text
4. fix the issue, commit changes
5. rebase changes against master
   $ git fetch upstream
   $ git rebase upstream/master
6. push to personal GitHub repository
   $ git push origin feature/RF-#####-some-text:feature/RF-#####-some-text
7. send pull request on GitHub against the master branch
8. link to the pull request in JIRA (using the Workflow button in the issue)
9. an integration manager will review your pull request
10. (optional) update code according to feedback. rebase, send and update pull request in JIRA (Workflow button)
11. the integration manager will merge your changes to master
12. the integration manager closes the pull request in JIRA (resolving the issue)

Release Requirements on Workflow

Proposed model is reflecting following requirements:

1. development for version
   • component freeze
   • feature freeze
   • stabilization phase
   • the length of each phase depends on the stage of the project (Alpha, Beta, CR, ER, Final)
2. release versioning
   • major releases
     • diverged from HEAD on master
   • minor releases
     • diverged from a pre-existing release tag
     • fixes incorporated into master may be ported to new minor release
3. release testing
   • bug-fixing and stabilization
     • diverge the release branch from master after release meets QA release criteria
     • stabilize the release branch separately
   • don't restrict feature development
     • master branch open after diverging release branch