[IPython-dev] (slightly OT) tags vs. branches

[Fernando Perez]

Hi David,

On Tue, Aug 16, 2011 at 8:05 PM, David Warde-Farley
<wardefar at iro.umontreal.ca> wrote:
> Gentlemen,
>
> I noticed you have both tags and branches related to releases. As I am currently in the midst of getting the Theano team up to speed on git (woohoo! we've switched!) and the GitHub pull request style of workflow (via gitwash and my various tl;dr cribbings from it), I wonder if you could enlighten me on why you have both, and what each might be useful for.

As Aaron indicated, having tags for releases is important to be able
to easily recover the exact commit that was used to make an official
release.  For this reason, it's important (as I've learned from
screwing up multiple times) to tag *after* you've made the release,
and you're sure that everything went up ok, uploaded to pypi, etc.  At
that point you create an annotated tag and push it to github, as
explained here (copied from the ipython release process and updated):

https://github.com/nipy/nitime/blob/master/doc/devel/how_to_release.rst

An additional benefit of using tags is that github automatically
creates downloadable tar/zipballs for any tag, so you get an automatic
download website by the mere act of pushing a tag.

Now, we only create numbered branches for cases when we do maintain a
release series in parallel with the main development. That was the
case for the 0.9.x and 0.10.x series, simply because what we now call
0.11 took forever to get into shape, and it was important to still
provide users with fixes to the released IPython while we cooked 0.11.
 But now that those branches are finished, we can get rid of them (to
keep the repo tidy) and simply leave the tags as reference points of
when the release was made (Min is actually going to do that cleanup
soon).

The other case when we do create extra branches on the repo is when
there is a major feature that requires extensive collaborative
development where we may want multiple core devs to be able to write
directly.  We did that last summer with some of the work that led to
0.11, and now we have the htmlnotebook branch for the same reason.
But once it gets merged, we'll delete the branch from the repo, as in
this case it's strictly convenience.

So in summary: branches to make development easy while things are
changing, tags to mark the point where releases were made so that
anyone can reconstruct the release later on (distributors, etc).

I should add (re. Aaron's comment) that in IPython we do try to review
most code, except for very small changes.  We only commit directly
typically things that fix a bug in a small, localized change and when
the bug is nasty, such as one that Aaron happened to report yesterday
that crashed IPython altogether.  I whipped up a localized fix and
committed it right away.  But in general, even core devs with commit
access submit all our work for review via pull requests, as you can
see from the pulls page:

https://github.com/ipython/ipython/pulls

which has PRs from pretty much everyone.

In my mind, review is always better than not, but with such a small
team we also use some judgment in allowing occasional changes to go in
directly when waiting for review would otherwise just paralyze things.
 We basically try to strike a balance between maximizing review (which
pretty much always increases code quality) and maintaining good
throughput.

I hope this helps, feel free to ask further.  And glad to see Theano on github!

Best,

f