HACKING - autoconf - Git at Google


            
            -*- outline -*-


            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


            ** If you incorporate a change from somebody on the net:

            
            First, if it is a large change, you must make sure they have signed

            
            the appropriate paperwork.  Second, be sure to add their name and

            
            email address to THANKS.


            ** Test fixes

            
            If a change fixes a test, mention the test in the ChangeLog entry.

            
            To this end, the Autotest-mode is handy.


            ** Bug reports

            
            If somebody reports a new bug, mention their name in the ChangeLog

            
            entry and in the test case you write.  Put them into THANKS.


            The correct response to most actual bugs is to write a new test case

            
            which demonstrates the bug.  Then fix the bug, re-run the test suite,

            
            and check everything in.


            ** Visible changes

            
            Which include serious bug fixes, must be mentioned in NEWS.


            ** Portability issues

            
            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

            
            Use liberally.


            ** Release checks

            
            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, shared from gnulib, and customized in

            
              cfg.mk.


            - Run 'make distcheck' and 'make maintainer-check'.


            - Try some real world packages

            
              A good example is the coreutils package.


            * Release Procedure

            
            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 <ftp-upload@gnu.org> 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

            
            Automake 1.11 or later (preferably not a development snapshot).  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.  If needed, update cfg.mk with details

            
            specific to your environment, such as the location of a gnulib checkout.


            ** Update the foreign files

            
            Running 'make fetch' in the top level should grab it all for you; you

            
            should check the results before committing them in git.


            ** Set the version number

            
            Update the version number in NEWS (with version, date, and release

            
            type).  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, 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'.


            ** Make the release

            
            Run 'make {alpha,beta,stable}' depending on which type of release this

            
            is.  This runs the various checks, creates delta files, creates a

            
            preliminary announcement in ~/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 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.


            ** Push the updates

            
            Run 'git push origin refs/tags/v<version>' to push the release tag.


            ** Announce

            
            Complete/fix the announcement file, and email it at least to

            
            autoconf@gnu.org and autotools-announce@gnu.org.  If this is a stable

            
            release, also mail to info-gnu@gnu.org; if it is a beta release,

            
            also mail to platform-testers@gnu.org.


            ** Other web updates

            
            For alpha and beta releases, the process is complete.  For stable

            
            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: browse to:

            
              https://directory.fsf.org/project/autoconf/

            
            and send an email to <bug-directory@gnu.org> mentioning any content

            
            that needs to be updated.


            -----


            Copyright (C) 2002, 2008-2017, 2020-2025 Free Software Foundation, Inc.


            Copying and distribution of this file, with or without modification,

            
            are permitted in any medium without royalty provided the copyright

            
            notice and this notice are preserved.  This file is offered as-is,

            
            without warranty of any kind.
	-- outline --

	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

	** If you incorporate a change from somebody on the net:
	First, if it is a large change, you must make sure they have signed
	the appropriate paperwork. Second, be sure to add their name and
	email address to THANKS.

	** Test fixes
	If a change fixes a test, mention the test in the ChangeLog entry.
	To this end, the Autotest-mode is handy.

	** Bug reports
	If somebody reports a new bug, mention their name in the ChangeLog
	entry and in the test case you write. Put them into THANKS.

	The correct response to most actual bugs is to write a new test case
	which demonstrates the bug. Then fix the bug, re-run the test suite,
	and check everything in.

	** Visible changes
	Which include serious bug fixes, must be mentioned in NEWS.

	** Portability issues
	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
	Use liberally.

	** Release checks
	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, shared from gnulib, and customized in
	cfg.mk.

	- Run 'make distcheck' and 'make maintainer-check'.

	- Try some real world packages
	A good example is the coreutils package.

	* Release Procedure
	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 <ftp-upload@gnu.org> 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
	Automake 1.11 or later (preferably not a development snapshot). 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. If needed, update cfg.mk with details
	specific to your environment, such as the location of a gnulib checkout.

	** Update the foreign files
	Running 'make fetch' in the top level should grab it all for you; you
	should check the results before committing them in git.

	** Set the version number
	Update the version number in NEWS (with version, date, and release
	type). 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, 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'.

	** Make the release
	Run 'make {alpha,beta,stable}' depending on which type of release this
	is. This runs the various checks, creates delta files, creates a
	preliminary announcement in ~/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 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.

	** Push the updates
	Run 'git push origin refs/tags/v<version>' to push the release tag.

	** Announce
	Complete/fix the announcement file, and email it at least to
	autoconf@gnu.org and autotools-announce@gnu.org. If this is a stable
	release, also mail to info-gnu@gnu.org; if it is a beta release,
	also mail to platform-testers@gnu.org.

	** Other web updates
	For alpha and beta releases, the process is complete. For stable
	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: browse to:
	https://directory.fsf.org/project/autoconf/
	and send an email to <bug-directory@gnu.org> mentioning any content
	that needs to be updated.

	-----

	Copyright (C) 2002, 2008-2017, 2020-2025 Free Software Foundation, Inc.

	Copying and distribution of this file, with or without modification,
	are permitted in any medium without royalty provided the copyright
	notice and this notice are preserved. This file is offered as-is,
	without warranty of any kind.