How to make a gnulib stable snapshot
		 ------------------------------------

by Ian Beckwith <address@hidden>
Last Update: Tue Apr 24 2010
Latest Version: http://erislabs.net/projects/gnulib/STABLE-HOWTO.html

BRANCHES

   * upstream - tracks git://git.savannah.gnu.org/gnulib.git
   * stable   - the stable snapshot we produce, based on upstream
   * master   - the debian branch, based on stable (optional)

PROCEDURE

   * if you don't already have a repository:

     + clone the gnulib repo:
         $ git clone git://git.savannah.gnu.org/gnulib.git
	 $ git branch -m master upstream

     + then either import the existing stable repo:
         $ git remote add erislabs git://erislabs.net/gnulib.git
	 $ git fetch erislabs
	 $ git branch stable erislabs/stable

     + or, if that isn't possible, start from scratch:
         $ git branch stable upstream

   * update upstream branch:
         $ git checkout upstream
         $ git pull

   * tag the current upstream HEAD for later use:
         $ git tag snapshot-start upstream

   * run the test suite:
         $ git checkout upstream
         $ ./gnulib-tool --create-megatestdir --with-tests  --dir=t 2>&1 | tee create.out
         $ cd t
         $ ./do-autobuild 2>&1 | tee ../build.out
         $ cd ..

   * find failing tests with:
         $ grep -L rc=0 t/logs/*

   * report any issues to address@hidden

   * merge the current upstream version into the stable branch:
         $ git checkout stable
         $ git merge upstream

   * resolve conflicts
         $ git checkout upstream <all conflicting paths except NEWS.stable>
         $ git commit -a

   * wait a week or so

   * update upstream branch:
         $ git checkout upstream
         $ git pull

   * create list of commits to review:
         $ git log --oneline --reverse --topo-order snapshot-start..upstream > ../stable.log

   * return to the stable branch
         $ git checkout stable

   * prepare NEWS.stable for new release.

     + add new header

     + add __NEXTCOMMITMARKER__ tag where you want commits to be logged

   * for each commit in ../stable.log:

     + review each commit in ../stable.log:
         $ git show commitid

     + if you want to cherry-pick that commit:
         $ stable-cherry-pick commitid
       (stable-cherry-pick source: http://erislabs.net/ianb/projects/gnulib/stable-cherry-pick)

     + if the cherry-pick fails:

       * resolve the conflict and commit, making a note of the new commitid

       * fill in the new commitid in NEWS.stable, then commit

   * remove __NEXTCOMMIT__ marker from NEWS.stable, commit

   * test (see above). If testsuite fails, check whether bug exists
     in upstream branch, report to address@hidden

   * remove the temporary snapshot-start tag
          $ git tag -d snapshot-start

   * tag the new release
          $ git tag stable/yymmdd

   * create and upload tarball:
          $ git archive --format=tar --prefix=gnulib-yymmdd-stable/ stable/yymmdd | gzip -9 > ../gnulib-yymmdd-stable.tar.gz

   * push changes to stable git repository

   * mail announcement to address@hidden