Skip to content

Branching

Jump to bottom Edit New page
jgonggrijp edited this page Apr 22, 2013 · 1 revision

This page builds onwards from Workflow. You can read this in isolation, but you should at least have a basic idea of what a branch is.

Table of Contents

The integration branch

Whenever we talk about the integration branch, we mean the master branch of the-xkcd-community/the-red-spider-project. As the name implies, this branch integrates all finished additions to the project. Every commit on this branch represents a coherent state of the project. Most of these commits are merged pull requests. upstream/master on your local clone should refer to the integration branch.

master branches on forks and clones don't have any special meaning. In principle you could treat your own master branch like any topic branch (see below), but it's recommended to have it mirror the integration branch instead and use topic branches with speaking names for your own work.

Topic branches

In a wide sense, all branches except for the integration branch are topic branches. In a narrower sense, we mean only branches that are used for a specific job. It's recommended that you use a separate topic branch for each job and that you name the topic branch after its associated job. For example, setup-modularize could be the name of a topic branch in which you're working on the modularisation of setup.py.

Topic branches tend to be temporary, because at some point the job gets either finished or abandoned. In the first case the topic branch will be integrated, i.e. pulled into the integration branch, and in both cases the ref will probably be deleted.

Satellites

When one topic branch (in the narrow sense) is created from another, you could call these topic branches each other's satellites (this is not regular Git jargon). Topic branches are usually started from the integration branch, probably indirectly through your local master branch. You may want to create satellites in order to divide the job into subtopics, to collaborate (if you branch from a remote topic branch) or to experiment with a special approach.

Satellites are merged or pulled back together (or abandoned) and the refs are deleted, until only a single topic branch remains. Just like all topic branches, that one is then integrated or abandoned.

Rules of thumb

These are really just recommendations to help you keep things tidy:

Do...

  • try to isolate small jobs so you can finish your topic branches quickly.
  • try to handle related jobs serially so you can do pull requests in between.
  • merge satellites into each other.
  • keep multiple (unrelated) topic branches in parallel, if you feel like working on multiple things at the same time.
  • pull the integration branch into any other branch, whenever you want. This is the best way to update your local branch with recent developments in other parts of the project.
  • use your master branch as a mirror of the integration branch so you can use it as a quick "launchpad" for your topic branches.
  • update your master branch when your pull request is merged, to bring the merge to your local clone and your fork.
  • delete the ref to your topic branch after doing that.
Don't...
  • commit anything to your master branch.
  • merge anything into your master branch directly (other than by pulling in updates from the integration branch).
  • merge or pull unrelated topic branches into each other. Instead, wait until one of them is integrated and then update the other with the latest state from the integration branch.

See also

Add a custom footer
Add a custom sidebar
Clone this wiki locally