HACKING

   1 -*- outline -*-
   2
   3 This file attempts to describe the maintainer-specific notes to follow
   4 when hacking Autoconf.  Don't put this file into the distribution.
   5 Don't mention it in the ChangeLog.  You may want to first see
   6 README-hacking for more general rules on building Autoconf from
   7 checked-out sources.
   8
   9 * Administrivia
  10
  11 ** If you incorporate a change from somebody on the net:
  12 First, if it is a large change, you must make sure they have signed
  13 the appropriate paperwork.  Second, be sure to add their name and
  14 email address to THANKS.
  15
  16 ** Test fixes
  17 If a change fixes a test, mention the test in the ChangeLog entry.
  18 To this end, the Autotest-mode is handy.
  19
  20 ** Bug reports
  21 If somebody reports a new bug, mention his name in the ChangeLog entry
  22 and in the test case you write.  Put him into THANKS.
  23
  24 The correct response to most actual bugs is to write a new test case
  25 which demonstrates the bug.  Then fix the bug, re-run the test suite,
  26 and check everything in.
  27
  28 ** Visible changes
  29 Which include serious bug fixes, must be mentioned in NEWS.
  30
  31 ** Portability issues
  32 Discoveries in portability matters should be written down in the
  33 documentation (what fails, why it fails, *where* it fails, and what's
  34 to be written instead?).
  35
  36 ** Allow bootstrapping
  37 Make sure that a fresh checkout of Autoconf can be bootstrapped using
  38 the previous stable release of Autoconf.  In other words, do not use
  39 newly-added features in configure.ac if doing so would require an
  40 installed git checkout to rerun `autoreconf -i' successfully.
  41
  42 * Test suite
  43
  44 ** make check
  45 Use liberally.
  46
  47 ** Release checks
  48 Try to run the test suite with more severe conditions before a
  49 release:
  50
  51 - Run `make syntax-check'
  52   This makes sure that the source files follow some consistent rules.
  53   The checks live in maint.mk, which is intended to be shared across
  54   several projects.  (Help in merging this to use gnulib's maint.mk
  55   would be appreciated).
  56
  57 - Run `make maintainer-distcheck'
  58   This is quite long.  It basically runs the test suite using a C++
  59   compiler instead of a C compiler, and within a severe environment
  60   (POSIXLY_CORRECT).
  61
  62 - Try some real world packages
  63   A good example is the coreutils package.
  64
  65 * Release Procedure
  66 These steps describe what a maintainer does to make a release; they
  67 are not needed for ordinary patch submission.
  68
  69 ** Upload Privileges
  70 If you have not yet registered your gpg public key and (preferred)
  71 email address with the FSF in relation to the Autoconf package, send
  72 an email, preferably GPG-signed, to <ftp-upload@gnu.org> that includes
  73 the following:
  74
  75   (a) name of package(s) that you are the maintainer for, and your
  76       preferred email address.
  77
  78   (b) an ASCII armored copy of your GnuPG key, as an attachment.
  79       ("gpg --export -a YOUR_KEY_ID > mykey.asc" should give you
  80       this.)
  81
  82 When you have received acknowledgement of your message, the proper GPG
  83 keys will be registered on ftp-upload.gnu.org and only then will you
  84 be authorized to upload files to the FSF ftp machines.  Beware; this
  85 process can take several days.
  86
  87 ** Mailing list Admin Privileges
  88 If you do not have access to the mailing list administrative
  89 interface, approach the list owners for the password.  Be sure to
  90 check the lists (esp. bug-autoconf) for outstanding bug reports also
  91 in the list of pending moderation requests.  This step is not strictly
  92 necessary, but helps.
  93
  94 ** Preparation for release
  95 Make sure you have GNU make installed.  Make sure your PATH includes a
  96 Automake 1.11 or later (preferably not a development snapshot).  Make
  97 sure your locale is sane, e.g. by exporting LC_ALL=C.  Bootstrap the
  98 checkout, and make sure the testsuite passes.  See above for more
  99 hints on the testsuite.  If needed, update cfg.mk with details
 100 specific to your environment, such as the location of a gnulib checkout.
 101
 102 ** Update the foreign files
 103 Running `make fetch' in the top level should grab it all for you; you
 104 should check the results before committing them in git.
 105
 106 ** Set the version number
 107 Update the version number in NEWS (with version, date, and release
 108 type) and ChangeLog, and mention in README whether the release is
 109 stable.  Make sure all changes are committed, then run `git tag -s -m
 110 <version> -u <gpg_key> v<version>'.  Do not push anything upstream at
 111 this point.  At this point, running `make _version', followed by `make
 112 news-date-check changelog-check' will validate that the information is
 113 formatted correctly.
 114
 115 ** Update configure
 116 As much as possible, make sure to release an Autoconf that uses
 117 itself.  That's easy: just be in the top level, and run
 118 `tests/autoconf'.  Or install this autoconf and run `autoreconf -f'.
 119
 120 ** Make the release
 121 Run `make {alpha,beta,stable}' depending on which type of release this
 122 is.  This runs the various checks, creates delta files, creates a
 123 preliminary announcement in ~/announce-autoconf-<version>, prints
 124 out the command to upload the files, and updates the previous version
 125 file.
 126
 127 If it fails, run `git tag -d v<version>', fix the problems, and go
 128 back to the step of setting the version.
 129
 130 ** Upload
 131 Put the tarballs where they should be, using the instructions
 132 regarding gnupload that were printed during the previous step.  Verify
 133 that the files are correctly uploaded before sending a release
 134 announcement.
 135
 136 ** Push the updates
 137 Run `git push origin refs/tags/v<version>' to push the release tag.
 138
 139 ** Announce
 140 Complete/fix the announcement file, and email it at least to
 141 autoconf@gnu.org and autotools-announce@gnu.org.  If this is a stable
 142 release, also mail to info-gnu@gnu.org.
 143
 144 ** Other web updates
 145 For alpha and beta releases, the process is complete.  For stable
 146 releases, there are several other web pages that need updates.
 147
 148 Update the online manual: Run `make web-manual', then copy the
 149 contents of doc/manual into a CVS checkout of the documentation
 150 repository.  Remember to use `cvs add -ko' so that RCS keywords in the
 151 generated output do not get expanded improperly.
 152   $ export CVS_RSH=ssh
 153   $ cvs -z3 -d:ext:<user>@cvs.sv.gnu.org:/web/autoconf co autoconf
 154
 155 Post a news blurb on https://savannah.gnu.org/projects/autoconf.
 156
 157 Update the Free Software Directory: browse to:
 158   http://directory.fsf.org/project/autoconf/
 159 and send an email to <bug-directory@gnu.org> mentioning any content
 160 that needs to be updated.
 161
 162 -----
 163
 164 Copyright (C) 2002, 2008, 2009, 2010 Free Software Foundation, Inc.
 165
 166 Copying and distribution of this file, with or without modification,
 167 are permitted in any medium without royalty provided the copyright
 168 notice and this notice are preserved.  This file is offered as-is,
 169 without warranty of any kind.