Re: Document current policy for development with git.

[Ralf Wildenhues]

Hi Stefano, Eric,

thanks for the review!

* Stefano Lattarini wrote on Tue, Jul 27, 2010 at 10:34:32PM CEST:
> At Tuesday 27 July 2010, Ralf Wildenhues wrote:
> 
> > +* The git tree currently carries a number of branches: master for the
> > +  current development, and release branches named branch-X.Y.  The maint
> > +  branch serves as common ground for both master and the active release
> > +  branches.  Changes intended for both should be applied to maint, which
> > +  should then be merged to release branches and master, of course after
> > +  suitable testing.  It is advisable to merge only after a set of related
> > +  commits have been applied.

> I like the wording.  However, I'd also like to see a simple example, such as
> the one you provided me with in a previous mail (which helped me a lot).  Do
> you think this would be overkill?

I agree that we shouldn't make the barrier for entry higher than
necessary, but OTOH, if people are not firm with git then they need to
post patches in the manner they are comfortable with; I'll rework them
in that case.

Anyway, how about the additional patch below?

> > +* There may be a number of longer-lived feature branches for new 
> > developments.
> > +  They should be based off of a common ancestor of all active branches to
> > +  which the feature should be merged later.  The next branch may serve as
> > +  common ground for feature merging and testing, should they not be ready
> > +  for master yet.

> Shouldn't we mention the "next" branch before, together with master and maint
> and branch-X.Y? That would make things clearer IMHO.  For the rest, good
> and clear.

Yeah, maybe.

> > +* master and release branches should not be rewound, i.e., should always
> > +  fast-forward, except maybe for privacy issues.

> What about adding this too?
> ``... privacy issues (e.g. if a developer has mistakenly pushed a commit
> containing private or sensitive data)''

I don't care much either way, but I don't really see what additional
information this would convey.

Cheers,
Ralf

    Add example git work flow; discuss merge --log.
    
    * HACKING: Update.
    Suggestion by Stefano Lattarini.

diff --git a/HACKING b/HACKING
index a4c918a..ad0ae49 100644
--- a/HACKING
+++ b/HACKING
@@ -113,6 +113,30 @@
   suitable testing.  It is advisable to merge only after a set of related
   commits have been applied.
 
+* Example work flow for patches to maint:
+
+  # 1. Checkout the "maint" branch:
+  git checkout maint
+
+  # 2. Apply the patch(es) with "git am" (or create them with $EDITOR):
+  git am -3 0*.patch
+  # 2a. Run required tests, if any ...
+
+  # 3. Merge maint into branch-1.11:
+  git checkout branch-1.11
+  git merge maint
+  # 3a. Run required tests, if any ...
+
+  # 4. Redo steps 3 and 3a for master:
+  git checkout master
+  git merge maint
+  # testing ...
+
+  # 5. Push the maint and master branches:
+  git push --dry-run origin maint branch-1.11 master
+  # if all seems ok, then actually push:
+  git push origin maint branch-1.11 master
+
 * For bug fixes of long-standing bugs, it may be useful to commit them to
   a new branch based off of the commit that introduced the bug, and merge
   this bugfix branch into active branches that descend from the buggy commit.
@@ -123,6 +147,10 @@
   common ground for feature merging and testing, should they not be ready
   for master yet.
 
+* For merges from branches other than maint, prefer 'git merge --log' over
+  plain 'git merge', so that a later 'git log' gives an indication of which
+  actual patches were merged even when they don't appear early in the list.
+
 * master and release branches should not be rewound, i.e., should always
   fast-forward, except maybe for privacy issues.  The maint branch should not
   be rewound except maybe after retiring a release branch or a new stable