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.
  55
  56 - Run `make maintainer-check'
  57   This is quite long.  It basically runs the test suite using a C++
  58   compiler instead of a C compiler, and within a severe environment
  59   (POSIXLY_CORRECT).
  60
  61 - Try some real world packages
  62   A good example is the coreutils package.
  63
  64 * Release Procedure
  65 These steps describe what a maintainer does to make a release; they
  66 are not needed for ordinary patch submission.
  67
  68 ** Upload Privileges
  69 If you have not yet registered your gpg public key and (preferred)
  70 email address with the FSF in relation to the Autoconf package, send
  71 an email, preferably GPG-signed, to <ftp-upload@gnu.org> that includes
  72 the following:
  73
  74   (a) name of package(s) that you are the maintainer for, and your
  75       preferred email address.
  76
  77   (b) an ASCII armored copy of your GnuPG key, as an attachment.
  78       ("gpg --export -a YOUR_KEY_ID > mykey.asc" should give you
  79       this.)
  80
  81 When you have received acknowledgement of your message, the proper GPG
  82 keys will be registered on ftp-upload.gnu.org and only then will you
  83 be authorized to upload files to the FSF ftp machines.  Beware; this
  84 process can take several days.
  85
  86 ** Mailing list Admin Privileges
  87 If you do not have access to the mailing list administrative
  88 interface, approach the list owners for the password.  Be sure to
  89 check the lists (esp. bug-autoconf) for outstanding bug reports also
  90 in the list of pending moderation requests.  This step is not strictly
  91 necessary, but helps.
  92
  93 ** Preparation for release
  94 Make sure you have GNU make installed.  Make sure your PATH includes a
  95 released version of Automake (and not a development snapshot);
  96 preferably 1.10.1 or later so you can build an LZMA tarball.  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.  Update cfg.mk with details specific to your
 100 environment, such as your GPG key and the location of a gnulib
 101 checkout.
 102
 103 ** Update the foreign files
 104 Running `make update' in the top level should make it all for you.
 105 FIXME - this is broken as of 2.62, now that most upstream files are
 106 stored in git rather than CVS.  Until this is fixed, manually copy the
 107 files listed in cfg.mk from a gnulib git checkout.
 108
 109 ** Set the version number
 110 Update the version number in NEWS (with version, date, and release
 111 type) and ChangeLog, and mention in README whether the release is
 112 stable.  `make news-date-check' and `make changelog-check' will
 113 validate that the information is formatted correctly.  Make sure all
 114 changes are committed, then run `git tag -s -m <version> -u <gpg_key>
 115 v<version>'.  Do not push anything upstream at this point.
 116
 117 ** Update configure
 118 As much as possible, make sure to release an Autoconf that uses
 119 itself.  That's easy: just be in the top level, and run
 120 `tests/autoconf'.  Or install this autoconf and run `autoreconf -f'.
 121
 122 ** LZMA tarball creation
 123 Using the `dist-lzma' option of Automake requires Automake 1.10.1, and
 124 fails for everyone who does not have LZMA installed, so for now
 125 Autoconf only requires Automake 1.10.  However, as maintainer, you
 126 should build an LZMA tarball.  By using Automake 1.10.1 or newer, you
 127 can run `make dist-lzma'; run this prior to the release target so that
 128 the release announcement will include the .tar.lzma file.
 129
 130 ** Make the release
 131 Run `make {alpha,beta,major}' depending on which type of release this
 132 is.  This runs the various checks, creates delta files, creates a
 133 preliminary announcement in /tmp/announce-autoconf-<version>, prints
 134 out the command to upload the files, and updates the previous version
 135 file.
 136
 137 If it fails, run `git tag -d v<version>', fix the problems, and go
 138 back to the step of setting the version.
 139
 140 ** Upload
 141 Put the tarballs/xdeltas where they should be, using the instructions
 142 regarding gnupload that were printed during the previous step.  Verify
 143 that the files are correctly uploaded before sending a release
 144 announcement.
 145
 146 ** Push the updates
 147 Run `git push origin refs/tags/v<version>' to push the release tag.
 148
 149 ** Announce
 150 Complete/fix the announcement file, and email it at least to
 151 autoconf@gnu.org and autotools-announce@gnu.org.  If this is a major
 152 release, also mail to info-gnu@gnu.org.
 153
 154 ** Other web updates
 155 For alpha and beta releases, the process is complete.  For major
 156 releases, there are several other web pages that need updates.
 157
 158 Update the online manual: Run `make web-manual', then copy the
 159 contents of doc/manual into a CVS checkout of the documentation
 160 repository.  Remember to use `cvs add -ko' so that RCS keywords in the
 161 generated output do not get expanded improperly.
 162   $ export CVS_RSH=ssh
 163   $ cvs -z3 -d:ext:<user>@cvs.sv.gnu.org:/web/autoconf co autoconf
 164
 165 Post a news blurb on https://savannah.gnu.org/projects/autoconf.
 166
 167 Update the Free Software Directory: Checkout the CVS source, then
 168 after making edits, mail the diff to <bug-directory@gnu.org>.
 169   $ cvs -d:pserver:anonymous@cvs.sv.gnu.org:/sources/directory \
 170       co directory/autoconf.txt
 171
 172 -----
 173
 174 Copyright (C) 2002, 2008 Free Software Foundation, Inc.
 175
 176 This program is free software: you can redistribute it and/or modify
 177 it under the terms of the GNU General Public License as published by
 178 the Free Software Foundation, either version 3 of the License, or
 179 (at your option) any later version.
 180
 181 This program is distributed in the hope that it will be useful,
 182 but WITHOUT ANY WARRANTY; without even the implied warranty of
 183 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
 184 GNU General Public License for more details.
 185
 186 You should have received a copy of the GNU General Public License
 187 along with this program.  If not, see <http://www.gnu.org/licenses/>.