Document current policy for development with git.

* HACKING (Working with git): Overhaul.
Prompted by suggestion from Stefano Lattarini.

Signed-off-by: Ralf Wildenhues <Ralf.Wildenhues@gmx.de>

1 files changed, 30 insertions, 12 deletions

diff --git a/HACKING b/HACKING
index ee859171a..8facbeb58 100644
--- a/HACKING
+++ b/HACKING
@@ -92,28 +92,46 @@
 
 
 ================================================================
-= Working with git/CVS
+= Working with git
 
 * To regenerate dependent files created by aclocal and automake,
   use the `bootstrap' script.  It uses the code from the source
   tree, so the resulting files (aclocal.m4 and Makefile.in) should
   be the same as you would get if you install this version of
-  automake and use it to generate those files.
+  automake and use it to generate those files.  Be sure to have the
+  latest stable version of Autoconf installed.
 
 * Dependent files aclocal.m4, configure and Makefile.in in all
   directories should be up to date in the git repository, so that
   the changes in them can be easily noticed and analyzed.
 
-* Avoid merge commits on the master branch of the public git repository.
-  For unpublished changes in your development tree, it's easiest to
-  rebase against the current master before applying them, this preserves
-  a linear history.
-
-* For changes to appear in more than one branch, apply them to the
-  master branch and then cherry-pick them to the stable branch from
-  master if possible.  This keeps the master uncluttered and preserves
-  meta-data on the stable branches.
-
+* 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.
+
+* 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.
+
+* 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.
+
+* 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
+  release.  For next, and for feature branches, the announcement for the
+  branch should document rewinding policy.
+
+* In order for rebasing and merging of ChangeLog entries to work seamlessly,
+  install and configure git-merge-changelog, currently available as gnulib
+  module.
 
 ================================================================
 = Test suite