Skip to content
kynan edited this page Aug 11, 2012 · 1 revision

Commits

  • every commit should be an independent change (patch) that can be viewed in isolating from others
  • conflating different changes in a single commit is discouraged
  • if in doubt, commits should be split into more elementary units, use the index (staging area) to your advantage
  • descriptive commit messages are mandatory, follow the Git commit message guidelines
  • use git add -p to interactively stage individual hunks from a file
  • use a GUI s.a. git-cola if you're not comfortable with the command line
  • to test only staged changes and temporarily mask out the other (non-staged) changes, use git stash --keep-index, test, commit, and restore the changes with git stash pop

Master branch

  • the master needs to be stable at all times i.e. every commit to master needs to pass the buildbot test suite
  • only small bugfixes for existing functionality are permissible for pushing to the master branch directly
  • larger changes and new features are developed in feature branches (see below) and integrated into master via pull requests and only after code review and passing the buildbot test suite

Feature / Topic branches

  • work on large new features or non-atomic fixes is done on a feature branch
  • feature branches have the feature/ prefix, bugfix branches the fix/ prefix
  • feature branches are regularly rebased on top of the latest upstream revision of the master branch and therefore must not be assumed to have a stable history
  • no other work should be based off feature branches, since every rebase would causes a cascade of further rebases of all descendants
  • before a pull request for a feature branch is submitted it should be cleaned up via interactive rebasing if necessary: pairs of commit/revert removed, fixup commits squashed with the commit they're fixing etc.
  • when the feature branch is considered ready for merge and passes all the tests, it is rebased on top of the upstream master, pushed to the central repository (or a fork) and a pull request is made
  • other developers review the pull request and suggest changes if necessary
  • the developer making the pull request is responsible for resolving any conflicts, rebasing the branch ensures it can be merged cleanly
  • once the pull request is approved, the developer that triggered it merges via github's automatic merge button or git merge --no-ff (creates a merge commit with two parents s.t. the feature branch appears as a sideline in the repository's history)
  • after the merge, the feature branch ref is cleared from the GitHub repository (git push origin :feature-branch)