geda-developers team mailing list archive

[Peter TB Brett <peter@xxxxxxxxxxxxx>]

On Fri, 30 Aug 2013 12:58:37 -0400, DJ Delorie <dj@xxxxxxxxxxx> wrote:
> Assuming we're talking about different git commands (a comparative
> analysis might be useful), let's at least agree to the intent of the
> patch branches?
> 
> IIRC the patch branches exist so that people can easily test a patch.
> Since we have so little testing, anything we can do to make it easy
> for people to test patches is a Good Thing.  Patch branches have two
> purposes: To give users a way to test "latest+patch", and to make sure
> patches don't bit-rot.
> 
> To that end, we should have a standard (and relatively easy) way to
> keep a branch at "latest master plus patch LP123", along with an easy
> way to merge that patch back to master when appropriate.

There's a few things to consider:

1) once you've established how you want to use your git repository, make
sure that it's easy to figure out.  If your working practice makes regular
use of `git push --force', it's *very important* that you make that clear
(because otherwise people can base work on the tip of the branch and get
the rug pulled out from under them when they try and contribute it back).

2) how important is it for the branch to be "latest master + LP###" rather
than "latest state of LP###"?  In geda-gaf, we sometimes use public patch
branches for people to try out, but these are almost always rooted at a
particular point in history.  Run `gitk 31440e054a54' in the geda-gaf repo
for an example of what this looks like.

3) there may be a distinction between how you make changes *within* a patch
branch, and how you merge the changes back once the branch is "ready".  In
the example I pointed out above, the patch branch was just merged back into
the master branch.  However, you could alternatively "squash" the branch
into a single patch, and add it as a single commit.  My libgedacairo
initial patch just adds the whole library in one go (see commit
be4ed1c509e9) even though that wasn't how I actually developed it in my
local repo.

4) Raw git rebase / cherry-pick for shuffling patches is a bit hairy. 
pcjc2 and I use Stacked Git (stgit) in our local/personal repos, which
provides the `stg' tool that makes things much, much easier to manage (for
example, you can keep a "stack" of unapplied patches, copy patches between
branches, directly edit commit messages, easily recover when things go
wrong, etc.)  If you decide that you want the feature branch workflow to
involve history smashing, you could do worse than to standardise on using
stgit (it even has convenient Emacs support).

5) if you decide that you definitely want feature branches to be "latest
master + LP###", then you can either regularly merge from master to the
feature branch, or you can regularly rebase the feature branch.  I would
normally use the merging strategy.  This is because (a) it makes it much
clearer how progress in developing the feature was affected by changes made
in the master branch (via any merge conflicts that occur) and (b) it makes
it easier for people who are using only basic git commands, and/or
beginners who are scared by rebase (I was!), to contribute.  On the other
hand, using the merging strategy *does* mean that you get a lot of merge
commits, and makes your history look messy.  But commits are cheap.  And
all git tools cope really well with merges.  And (as discussed above) you
can squash it all into a single patch when the branch is fully cooked if
you want things to look pretty.

6) When you're done with a branch (i.e. it's fully merged) you might want
to delete the branch (because it's all now included in the master branch). 
Explicitly merging the branch back can make it easier to verify that yes,
it's actually safe to delete the branch. 

Did any of that make sense?

Peter

-- 
Dr Peter Brett
http://peter-b.co.uk/