Re: Document current policy for development with git.

[Stefano Lattarini]

At Tuesday 27 July 2010, Ralf Wildenhues wrote:
> Hi Stefano, all,
> 
> I've rewritten the HACKING section on development with git a bit to
> better reflect what I currently think is a good way to go on. 
> Patch for maint.  Comments appreciated.
> 
> FYI, I am waiting for regenerating the in-tree files with Autoconf
> 2.67 until the official tarballs have come out.
See the "tangential issue" below about this...

> Thanks,
> Ralf
> 
>     Document current policy for development with git.
> 
>     * HACKING (Working with git): Overhaul.
>     Prompted by suggestion from Stefano Lattarini.
> 
> diff --git a/HACKING b/HACKING
> index ee85917..8facbeb 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.
Somewhat of a tangetial issue here...
I suggest that we modify the bootstrap script to offer an easy way to
override which autoconf command is used (currently there is just a call
to "autoconf" directly).  This might help developers who want their
systems to stick with older autoconf by default -- they might have
/usr/bin/autoconf or /usr/local/bin/autoconf being, say, autoconf 2.64,
and have autoconf 2.67 installed only as /usr/local/bin/autoconf-2.67.
Ideally they should be able to do:
  $ AUTOCONF=autoconf-2.67 ./bootstrap
and have everything working seamlessly.  WDYT?

>  * 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.
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?

> +* 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.
Good and clear.

> +* 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.

> +* 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)''

> +  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.
Good and clear.

Thanks,
   Stefano