Re: 2.62 nearly ready

[Eric Blake]

Eric Blake <ebb9 <at> byu.net> writes:

> The permissions problem has been resolved; I've completed uploading the 
> tarballs to ftp.gnu.org, and am checking in this as part of updating the 
online 
> manual.

And so I don't forget everything I did for this release:

>From 6fa1ed23e122325c69b610274ec81af87d20e6ef Mon Sep 17 00:00:00 2001
From: Eric Blake <address@hidden>
Date: Wed, 9 Apr 2008 10:15:28 -0600
Subject: [PATCH] Update various hacking notes.

* HACKING: Add more maintainer-specific details.
* README-hacking: Add more general-contributor details.

Signed-off-by: Eric Blake <address@hidden>
---
 HACKING        |  154 +++++++++++++++++++++++++++++++++++++++++---------------
 README-hacking |   70 +++++++++++++++++++++----
 2 files changed, 172 insertions(+), 52 deletions(-)

diff --git a/HACKING b/HACKING
index e6cb3a3..ad21ce9 100644
--- a/HACKING
+++ b/HACKING
@@ -1,8 +1,10 @@
--*- outline -*-or
+-*- outline -*-
 
-This file attempts to describe the rules to use when hacking Autoconf.
-Don't put this file into the distribution.  Don't mention it in the
-ChangeLog.
+This file attempts to describe the maintainer-specific notes to follow
+when hacking Autoconf.  Don't put this file into the distribution.
+Don't mention it in the ChangeLog.  You may want to first see
+README-hacking for more general rules on building Autoconf from
+checked-out sources.
 
 * Administrivia
 
@@ -31,6 +33,12 @@ Discoveries in portability matters should be written down in 
the
 documentation (what fails, why it fails, *where* it fails, and what's
 to be written instead?).
 
+** Allow bootstrapping
+Make sure that a fresh checkout of Autoconf can be bootstrapped using
+the previous stable release of Autoconf.  In other words, do not use
+newly-added features in configure.ac if doing so would require an
+installed git checkout to rerun `autoreconf -i' successfully.
+
 * Test suite
 
 ** make check
@@ -40,60 +48,126 @@ Use liberally.
 Try to run the test suite with more severe conditions before a
 release:
 
+- Run `make syntax-check'
+  This makes sure that the source files follow some consistent rules.
+  The checks live in maint.mk, which is intended to be shared across
+  several projects.
+
 - Run `make maintainer-check'
   This is quite long.  It basically runs the test suite using a C++
   compiler instead of a C compiler, and within a severe environment
   (POSIXLY_CORRECT).
 
 - Try some real world packages
-  Good example is the coreutils package.
+  A good example is the coreutils package.
 
 * Release Procedure
-
-** Tests
-See above.
+These steps describe what a maintainer does to make a release; they
+are not needed for ordinary patch submission.
+
+** Upload Privileges
+If you have not yet registered your gpg public key and (preferred)
+email address with the FSF in relation to the Autoconf package, send
+an email, preferably GPG-signed, to <address@hidden> that includes
+the following:
+
+  (a) name of package(s) that you are the maintainer for, and your
+      preferred email address.
+
+  (b) an ASCII armored copy of your GnuPG key, as an attachment.
+      ("gpg --export -a YOUR_KEY_ID > mykey.asc" should give you
+      this.)
+
+When you have received acknowledgement of your message, the proper GPG
+keys will be registered on ftp-upload.gnu.org and only then will you
+be authorized to upload files to the FSF ftp machines.  Beware; this
+process can take several days.
+
+** Mailing list Admin Privileges
+If you do not have access to the mailing list administrative
+interface, approach the list owners for the password.  Be sure to
+check the lists (esp. bug-autoconf) for outstanding bug reports also
+in the list of pending moderation requests.  This step is not strictly
+necessary, but helps.
+
+** Preparation for release
+Make sure you have GNU make installed.  Make sure your PATH includes a
+released version of Automake (and not a development snapshot);
+preferably 1.10.1 or later so you can build an LZMA tarball.  Make
+sure your locale is sane, e.g. by exporting LC_ALL=C.  Bootstrap the
+checkout, and make sure the testsuite passes.  See above for more
+hints on the testsuite.  Update cfg.mk with details specific to your
+environment, such as your GPG key and the location of a gnulib
+checkout.
 
 ** Update the foreign files
 Running `make update' in the top level should make it all for you.
+FIXME - this is broken as of 2.62, now that most upstream files are
+stored in git rather than CVS.  Until this is fixed, manually copy the
+files listed in cfg.mk from a gnulib git checkout.
+
+** Set the version number
+Update the version number in NEWS (with version, date, and release
+type) and ChangeLog, and mention in README whether the release is
+stable.  `make news-date-check' and `make changelog-check' will
+validate that the information is formatted correctly.  Make sure all
+changes are committed, then run `git tag -s -m <version> -u <gpg_key>
+v<version>'.  Do not push anything upstream at this point.
 
 ** Update configure
-As much as possible, to try an Autoconf that uses itself.  That's
-easy: just be in the top level, and run tests/autoconf.  Or install
-this autoconf and autoreconf -f.
-
-** Update NEWS
-The version number, *and* the date of the release (including for
-betas).
-
-** Update ChangeLog
-Should have an entry similar to `Version 2.53b.'.
-Check all this in once `make distcheck' passes.
-
-** make alpha
-Running `make alpha' is absolutely perfect for beta releases: it makes
-the tarballs, the xdeltas, and prepares (in /tmp/) a proto
-announcement.  It is so neat, that that's what I use anyway for
-genuine releases, but adjusting things by hand (e.g., the urls in the
-announcement file, the ChangeLog which is not needed etc.).
-
-If it fails, you're on your own...
-
-It requires GNU Make.
+As much as possible, make sure to release an Autoconf that uses
+itself.  That's easy: just be in the top level, and run
+`tests/autoconf'.  Or install this autoconf and run `autoreconf -f'.
+
+** LZMA tarball creation
+Using the `dist-lzma' option of Automake requires Automake 1.10.1, and
+fails for everyone who does not have LZMA installed, so for now
+Autoconf only requires Automake 1.10.  However, as maintainer, you
+should build an LZMA tarball.  By using Automake 1.10.1 or newer, you
+can run `make dist-lzma'; run this prior to the release target so that
+the release announcement will include the .tar.lzma file.
+
+** Make the release
+Run `make {alpha,beta,major}' depending on which type of release this
+is.  This runs the various checks, creates delta files, creates a
+preliminary announcement in /tmp/announce-autoconf-<version>, prints
+out the command to upload the files, and updates the previous version
+file.
+
+If it fails, run `git tag -d v<version>', fix the problems, and go
+back to the step of setting the version.
 
 ** Upload
-Put the tarballs/xdeltas where they should be.  Or put it somewhere,
-and send the URL to address@hidden
+Put the tarballs/xdeltas where they should be, using the instructions
+regarding gnupload that were printed during the previous step.  Verify
+that the files are correctly uploaded before sending a release
+announcement.
 
-** Bump the version number
-In configure.ac.  Run `make', check this in.
+** Push the updates
+Run `git push origin refs/tags/v<version>' to push the release tag.
 
 ** Announce
-Complete/fix the announcement file, and send it at least to
address@hidden (if a real release, or a ``serious beta''),
address@hidden (even for ``non serious beta''),
address@hidden, address@hidden, address@hidden, and
address@hidden
-
+Complete/fix the announcement file, and email it at least to
address@hidden and address@hidden  If this is a major
+release, also mail to address@hidden
+
+** Other web updates
+For alpha and beta releases, the process is complete.  For major
+releases, there are several other web pages that need updates.
+
+Update the online manual: Run `make web-manual', then copy the
+contents of doc/manual into a CVS checkout of the documentation
+repository.  Remember to use `cvs add -ko' so that RCS keywords in the
+generated output do not get expanded improperly.
+  $ export CVS_RSH=ssh
+  $ cvs -z3 -d:ext:<user>@cvs.sv.gnu.org:/web/autoconf co autoconf
+
+Post a news blurb on https://savannah.gnu.org/projects/autoconf.
+
+Update the Free Software Directory: Checkout the CVS source, then
+after making edits, mail the diff to <address@hidden>.
+  $ cvs -d:pserver:address@hidden:/sources/directory \
+      co directory/autoconf.txt
 
 -----
 
diff --git a/README-hacking b/README-hacking
index 626c631..0b8b0d9 100644
--- a/README-hacking
+++ b/README-hacking
@@ -1,7 +1,10 @@
 -*- outline -*-
 
 These notes intend to help people working on the checked-out sources.
-These requirements do not apply when building from a distribution tarball.
+These requirements do not apply when building from a distribution
+tarball.  Don't put this file into the distribution.  Don't mention it
+in the ChangeLog.  You may want to also see HACKING for
+maintainer-specific rules.
 
 * Requirements
 
@@ -19,44 +22,87 @@ tools we depend upon, including:
 - Texinfo 4.8+ <http://www.gnu.org/software/texinfo/>
 
 The following are useful as well, if you want to be able to run commands
-like "make dist" or "make distcheck":
+like "make dist-lzma" or "make distcheck":
 
 - Gzip <http://www.gnu.org/software/gzip/>
 - Tar <http://www.gnu.org/software/tar/>
+- LZMA Utils 4.32+ <http://tukaani.org/lzma/>
 
 Only building the initial full source tree will be a bit painful.
 Later, a plain `git pull && make' should be sufficient.
 
 * First GIT checkout
 
-You can get a copy of the source repository like this:
+You can get an anonymous copy of the source repository using any one
+of these three methods, although the CVS mirror is less tested:
 
-       $ git clone git://git.sv.gnu.org/autoconf
+  $ git clone git://git.sv.gnu.org/autoconf
+  $ git clone http://git.sv.gnu.org/r/autoconf.git
+  $ cvs -d:pserver:address@hidden:/srv/git/autoconf.git \
+      co -d autoconf HEAD
+
+If you have a Savannah user name and commit rights to the Autoconf
+project, you should use this instead:
+
+  $ git clone <username>@git.sv.gnu.org:/srv/git/autoconf.git
 
 The next step is to generate files like configure and Makefile.in:
 
-       $ cd autoconf
-       $ autoreconf -vi
+  $ cd autoconf
+  $ autoreconf -vi
 
 Since we're building autoconf itself, and its tests are picky, the
 following procedure includes an extra step to ensure that some
-generated files are regenerated using the tools just build by "make":
+generated files are regenerated using the tools just build by "make"
+(if you use GNU make, the file GNUmakefile sets PATH for you):
 
-       $ ./configure
-       $ make
-       $ ( PATH=`pwd`/tests:$PATH; autoreconf -vi )
-       $ make check
+  $ ./configure
+  $ make
+  $ ( PATH=`pwd`/tests:$PATH; autoreconf -vi )
+  $ make check
 
 At this point, there should be no difference between your local copy,
 and the GIT master copy:
 
-       $ git diff
+  $ git diff
 
 should output no difference.
 
+The testsuite is run by 'make check'.  You may find it useful to run a
+subset of the testsuite; for example, all tests with the 'm4sugar'
+keyword as well as test 10:
+
+  $ make check TESTSUITEFLAGS='10 -k m4sugar'
+
+* Submitting patches
+
+All patches should be submitted to <address@hidden> for
+review, in context or unified diff format against the latest sources.
+In most cases, a patch should include a test case, to ensure that
+regressions do not creep back in.  Remember to add documentation and a
+NEWS entry for anything that is visible to the user.
+
 You may find it useful to install the git-merge-changelog merge driver:
 http://git.sv.gnu.org/gitweb/?p=gnulib.git;a=blob;f=lib/git-merge-changelog.c
 
+If your change is significant (i.e., if it adds more than ~10 lines),
+then you'll have to have a copyright assignment on file with the FSF.
+Since that involves first an email exchange between you and the FSF,
+and then the exchange (FSF to you, then back) of an actual sheet of paper
+with your signature on it, and finally, some administrative processing
+in Boston, the process can take a few weeks.
+
+The forms to choose from are in gnulib's doc/Copyright/ directory.
+If you want to assign a single change, you should use the file,
+doc/Copyright/request-assign.changes:
+
+    http://git.sv.gnu.org/gitweb/?p=gnulib.git;a=blob;f=doc/Copyright/request-
assign.changes;hb=HEAD
+
+If you would like to assign past and future autoconf work,
+you'd use doc/Copyright/request-assign.future:
+
+    http://git.sv.gnu.org/gitweb/?p=gnulib.git;a=blob;f=doc/Copyright/request-
assign.future;hb=HEAD
+
 Enjoy!
 
 -----
-- 
1.5.5