Port minor AC_HEADER_MAJOR fixes from Gnulib
[autoconf.git] / HACKING
blob1bd30ac5a085abb81142cd9695a64c70830b5064
1 -*- outline -*-
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.
9 * Administrivia
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.
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.
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.
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.
28 ** Visible changes
29 Which include serious bug fixes, must be mentioned in NEWS.
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?).
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.
42 * Test suite
44 ** make check
45 Use liberally.
47 ** Release checks
48 Try to run the test suite with more severe conditions before a
49 release:
51 - Run `make syntax-check'
52   This makes sure that the source files follow some consistent rules.
53   The checks live in maint.mk, shared from gnulib, and customized in
54   cfg.mk.
56 - Run `make distcheck' and `make maintainer-check'.
58 - Try some real world packages
59   A good example is the coreutils package.
61 * Release Procedure
62 These steps describe what a maintainer does to make a release; they
63 are not needed for ordinary patch submission.
65 ** Upload Privileges
66 If you have not yet registered your gpg public key and (preferred)
67 email address with the FSF in relation to the Autoconf package, send
68 an email, preferably GPG-signed, to <ftp-upload@gnu.org> that includes
69 the following:
71   (a) name of package(s) that you are the maintainer for, and your
72       preferred email address.
74   (b) an ASCII armored copy of your GnuPG key, as an attachment.
75       ("gpg --export -a YOUR_KEY_ID > mykey.asc" should give you
76       this.)
78 When you have received acknowledgement of your message, the proper GPG
79 keys will be registered on ftp-upload.gnu.org and only then will you
80 be authorized to upload files to the FSF ftp machines.  Beware; this
81 process can take several days.
83 ** Mailing list Admin Privileges
84 If you do not have access to the mailing list administrative
85 interface, approach the list owners for the password.  Be sure to
86 check the lists (esp. bug-autoconf) for outstanding bug reports also
87 in the list of pending moderation requests.  This step is not strictly
88 necessary, but helps.
90 ** Preparation for release
91 Make sure you have GNU make installed.  Make sure your PATH includes a
92 Automake 1.11 or later (preferably not a development snapshot).  Make
93 sure your locale is sane, e.g. by exporting LC_ALL=C.  Bootstrap the
94 checkout, and make sure the testsuite passes.  See above for more
95 hints on the testsuite.  If needed, update cfg.mk with details
96 specific to your environment, such as the location of a gnulib checkout.
98 ** Update the foreign files
99 Running `make fetch' in the top level should grab it all for you; you
100 should check the results before committing them in git.
102 ** Set the version number
103 Update the version number in NEWS (with version, date, and release
104 type).  Make sure all changes are committed, then run `git tag -s -m
105 <version> -u <gpg_key> v<version>'.  Do not push anything upstream at
106 this point.
108 ** Update configure
109 As much as possible, make sure to release an Autoconf that uses
110 itself.  That's easy: just be in the top level, and run
111 `tests/autoconf'.  Or install this autoconf and run `autoreconf -f'.
113 ** Make the release
114 Run `make {alpha,beta,stable}' depending on which type of release this
115 is.  This runs the various checks, creates delta files, creates a
116 preliminary announcement in ~/announce-autoconf-<version>, prints
117 out the command to upload the files, and updates the previous version
118 file.
120 If it fails, run `git tag -d v<version>', fix the problems, and go
121 back to the step of setting the version.
123 ** Upload
124 Put the tarballs where they should be, using the instructions
125 regarding gnupload that were printed during the previous step.  Verify
126 that the files are correctly uploaded before sending a release
127 announcement.
129 ** Push the updates
130 Run `git push origin refs/tags/v<version>' to push the release tag.
132 ** Announce
133 Complete/fix the announcement file, and email it at least to
134 autoconf@gnu.org and autotools-announce@gnu.org.  If this is a stable
135 release, also mail to info-gnu@gnu.org; if it is a beta release,
136 also mail to platform-testers@gnu.org.
138 ** Other web updates
139 For alpha and beta releases, the process is complete.  For stable
140 releases, there are several other web pages that need updates.
142 Update the online manual: Run `make web-manual', then copy the
143 contents of doc/manual into a CVS checkout of the documentation
144 repository.  Remember to use `cvs add -ko' so that RCS keywords in the
145 generated output do not get expanded improperly.
146   $ export CVS_RSH=ssh
147   $ cvs -z3 -d:ext:<user>@cvs.sv.gnu.org:/web/autoconf co autoconf
149 Post a news blurb on https://savannah.gnu.org/projects/autoconf.
151 Update the Free Software Directory: browse to:
152   https://directory.fsf.org/project/autoconf/
153 and send an email to <bug-directory@gnu.org> mentioning any content
154 that needs to be updated.
156 -----
158 Copyright (C) 2002, 2008-2017, 2020 Free Software Foundation, Inc.
160 Copying and distribution of this file, with or without modification,
161 are permitted in any medium without royalty provided the copyright
162 notice and this notice are preserved.  This file is offered as-is,
163 without warranty of any kind.