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
