Git Flow

Git Flow

Maintained by Andrew Smith

Archivr follows the Git Flow branching model.

Salient takeaways:

• Do not fork the shared repo. All devs work off local clones of the shared repo.

• master represents a versioned, stable release

• develop is the branch leading to a new release.

• Available prefixes (modified for our group):

  • feature-
  • release-
  • hotfix-
  • support-

• Feature branches

  • Format: feature-<branchName>-#<issueNumber>
  • Features are cut from develop. This is where developers work.
  • Feature branches are rebased before submitting a pull request to simplify history graph and ease merging after PR approval
  • Feature branches are proposed to merge back into develop through a pull request.
  • After pull request is approved, feature is merged with --no-ff (either through command line or using GitHub). Branch on shared repo is then deleted.
  • When develop has a new branch merged, all developers rebase their feature branch off the current develop.

• Release branches

  • release-<version> branches are cut from develop.
  • No new features are added, only code cleanup and final testing.
  • Release branches are merged into the master and develop branches using the --no-ff option.

• Only the master and develop branches stick around; all other branch prefixes (feature, hotfix, support, etc.) are temporary and should be deleted after they are merged to the appropriate location.

Waffle.io integration

Maintained by Andrew Smith

• Append an issue number in the branch name with -#<issueNumber> to track in waffle.io. E.g. creating branch feature-setup-travis-#31 will take issue #31 and move it into "in progress" and assign it to you.
• All feature branches should relate to an issue.
• Pull requests should reference one or more issues.
• In comment for PR, reference issue being closed with keyword Closes. E.g. Closes #31. Will automatically move the card in Waffle to "Review"

The finer points of feature branches and merging

You cut your feature feature-dogs from develop. You make some commits. Meanwhile, develop progresses when someone merges in their own feature. After the rebase, the current branch looks like this:

feature-dogs          a1 -- a2    
                     /
develop        A -- B -- C 

Whether you continue work on feature-dogs or you want to merge in your own work, you need to rebase your feature branch with develop. You'll need to pull down the changes on develop, then rebase. Do it like this:

git checkout develop
git pull origin develop
git checkout feature-dogs
git rebase develop

You may run into merging conflicts; deal with them as necessary. If merge conflicts terrify you, seek help or read a tutorial -- they're not as scary as they seem. Your resulting git history should look like this:

feature-dogs               a1 -- a2    
                          /
develop        A -- B -- C 

When you're ready to merge back to develop, make sure you've rebased your feature branch before submitting a pull request. Otherwise, the project maintainer will need to rebase it themselves, which is just sad times.

After rebasing your feature branch, push it to the shared repo:

git push origin feature-<feature_name>

In GitHub, submit a pull request. Reference the issue that it closes.

Once all is done, the history will look like this:

feature-dogs               a1 -- a2    
                          /        \
develop        A -- B -- C -------- D

Project maintainers: Further details on how to locally rebase and merge a pull request are described here.

Other fun stuff

Your pull requests should reference and close the associated issues in GitHub. Always write something like fixes #34 or closes #2 in your commit message. More info here.