From f8bb7242a1a9d3a942c0be025528880ac582af33 Mon Sep 17 00:00:00 2001 From: Eric Blake 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 --- HACKING | 154 ++++++++++++++++++++++++++++++++++++++++++--------------- README-hacking | 70 +++++++++++++++++++++----- 2 files changed, 172 insertions(+), 52 deletions(-) diff --git a/HACKING b/HACKING index e6cb3a3a..27848e51 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 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 -u +v'. 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-, prints +out the command to upload the files, and updates the previous version +file. + +If it fails, run `git tag -d v', 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 ftp-upload@gnu.org. +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' to push the release tag. ** Announce -Complete/fix the announcement file, and send it at least to -info-gnu@gnu.org (if a real release, or a ``serious beta''), -autotools-announce@gnu.org (even for ``non serious beta''), -autoconf@gnu.org, automake@gnu.org, libtool@gnu.org, and -bug-gnu-utils@gnu.org. - +Complete/fix the announcement file, and email it at least to +autoconf@gnu.org and autotools-announce@gnu.org. If this is a major +release, also mail to info-gnu@gnu.org. + +** 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:@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 . + $ cvs -d:pserver:anonymous@cvs.sv.gnu.org:/sources/directory \ + co directory/autoconf.txt ----- diff --git a/README-hacking b/README-hacking index 626c6311..0b8b0d93 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+ 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 - Tar +- LZMA Utils 4.32+ 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:anonymous@pserver.git.sv.gnu.org:/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 @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 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! ----- -- 2.11.4.GIT