HACKING - m4 - Git at Google

 GNU M4
 ******

 1. Introduction
 ===============

 This file attempts to describe the processes we use to maintain M4,
 and is not part of a release distribution.


 2. Maintenance Notes
 ====================

 * If you incorporate a change from somebody on the net:
   If it is a large change, you must make sure they have signed the
   appropriate paperwork, and be sure to add their name and email
   address to THANKS.  AUTHORS is built from the FSF list of copyright
   assignments, on fencepost.gnu.org.

 * If somebody reports a new bug, write a test case, then mention his
   name in the ChangeLog entry.

 * 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.

 * Changes with user-visible effects must be mentioned in NEWS.

 * GNU Coding Standards should be followed:
     http://www.gnu.org/prep/standards/
   Additionally, while GNU M4 is not yet POSIX compliant, we are trying
   to get closer to it (although some design decisions state that POSIX
   compliance should only happen when POSIXLY_CORRECT is in the
   environment or the -G option was passed on the command line):
     http://www.opengroup.org/onlinepubs/009695399/utilities/m4.html


 3. Bootstrapping
 ================

 * The master M4 repository is stored in git.

 * Before you can build from git, you need to bootstrap.  This requires:
   - A pre-installed version of GNU M4 1.4.5 or later, built from a package
   - Autoconf 2.60 or later
   - Automake 1.10.1 or later
   - Help2man 1.29 or later
   - LZMA Utils 4.32 or later (from <http://tukaani.org/lzma/>)
   - Texinfo 4.8 or later
   - Any prerequisites of the above (such as perl, tex)
   - A git checkout of gnulib.  A read-only copy of gnulib can be
     obtained by:
       git clone git://git.sv.gnu.org/gnulib.git
     or
       cvs -d:pserver:anonymous@pserver.git.sv.gnu.org:/srv/git/gnulib.git \
         co -d gnulib HEAD

   If you are a member of the savannah group for gnulib, a read-write
   copy can be obtained by:
     git clone <savannah-user>@git.sv.gnu.org:/srv/git/gnulib.git

   Note that none of these bootstrapping dependencies should be required
   by a distributed release.

 * M4 has an optional build dependency.  In order to ensure that the
   dependency remains optional, you can avoid the library by using
   `./configure --without-libsigsegv-prefix'.  In order to ensure that
   the dependency is still viable with the current code base, you should
   install:
   - Libsigsegv 2.6 or later

 * Either add the gnulib directory to your PATH, or run
     GNULIB_TOOL=path/to/gnulib/gnulib-tool ./bootstrap

 * When it is time for a release, it is a good idea to bootstrap with
   official releases of the autotools, rather than git builds, to reduce
   the pain of a user re-running bootstrap on the packaged M4.  However,
   files installed by Automake should be updated to the latest version
   from their respective upstream source, rather than the version that
   shipped with the automake release.


 4. Test Suite
 =============

 * Use
     make check
   liberally, on as many platforms as you can.  Use as many compilers and
   linkers you can.

 * For branch-1.6, the testsuite is generated from the documentation.
   All instances of @example in doc/m4.texinfo that are not preceeded by
   "@comment ignore" are turned into tests in the checks directory.


 5. Editing 'ChangeLog'
 ======================

 * When in doubt, check that emacs can syntax-color properly in
   change-log-mode.  And preferably use emacs 'C-x 4 a'
   (add-change-log-entry-other-window) to open ChangeLog with an
   appropriate new template.

 * If this change is by a different author, or on a different date to the
   last entry start a new entry at the top of the file with the format
   (note two spaces between each field):

 yyyy-mm-dd  Name of Author  <email@address>

 *  If more than one person collaborated on the change, additional
    authors can be listed on subsequent lines, thus:

 yyyy-mm-dd  Name of Main Author  <email@address>,
             Name of Contributor  <another@email.address>

 * Where a change author did not supply a copyright assignment, but the
   changes they submitted were sufficiently trivial to commit in any case
   (see the GCS for guidelines on this), then flag this against their
   name in the header, thus:

 yyyy-mm-dd  Name of Author  <email@address>  (tiny change)

 * Preferably the next part should be a description of the overall
   purpose of the change, separated from the header by a blank line,
   indented by 1 tab, and filled at column 72.  The last character of the
   description should be a colon, :.

 * Changes to each file come next.  Each new file starts on a new line,
   indented by 1 tab and starting with an asterisk and a space.  Multiple
   files can be listed here relative to $top_srcdir, and comma separated.
   Names of functions (or sections as appropriate) to which the change
   applies should be named inside parentheses and comma separated.  If
   this goes beyond column 72, then parens should be closed and re-opened
   on the next line:

 	* file, another/file, test/testcases/foo.test (func_foo)
 	(func_bar, func_baz): Description of changes.

 * If the change does not apply to particular functions (or sections),
   the section list can be omitted:

 	* file, another/file, test/testcases/foo.test: General changes.

 * If the changes are particular to certain architectures, they should be
   listed after the functions in square brackets:

 	* file, another/file (func_foo) [linux, solaris]: Description of
 	changes.

 * Subsequent changes in other files that are related to the same overall
   enhancement or bugfix should be listed concurrently, without blank
   lines.  Always start a fresh line for a new file:

 	* file, another/file (func_foo) [linux, solaris]: Description of
 	changes.
 	* doc/foo.texi (Invoking Foo): Document.
 	* NEWS: Updated.

 * If the change is in response to a problem reported by someone other
   than the author, then credit them at the end of the description with:

 	Reported by Reporter Name <email@address>.

 * See the GNU Coding Standards document for more details on ChangeLog
   formatting.


 6. Release Procedure
 ====================

 * If you are an m4 maintainer, but have not yet registered your
   gpg public key and (preferred) email address with the FSF, 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.

 * 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-m4) for outstanding bug reports also in the list of
   pending moderation requests.  This step is not strictly necessary, but
   helps, since by default, m4-announce rejects all posts, so you have to
   get an administrator to allow your announcement through.

 * Make sure you have wget installed.

 * Make sure you have a copy of xdelta installed, and a copy of the previous
   release tarball in the build directory.

 * Make sure you have GNU make installed.

 * Make sure you have an up-to-date version of help2man installed.

 * Make sure your locale is sane, e.g. by exporting LC_ALL=C.

 * Update the version number in NEWS and ChangeLog, and mention in README
   whether the release is stable.  See
   http://www.gnu.org/software/libtool/contribute.html for details of the
   numbering scheme (M4 uses a similar scheme to libtool, although
   intra-release versions carry more information thanks to
   git-version-gen).

 * Run ./bootstrap.

 * Run ./configure (a VPATH build should work, but is less tested).

 * Run `make'.  The file doc/m4.1 needs to exist for a distribution, and
   be up-to-date with m4 --help output, but `make dist' intentionally
   does not depend on running a built binary.

 * Run `git commit' from the source tree if there are any changes from
   the previous steps.

 * Run `git tag -s -m <version> -u <gpg_key> v<version>' with the desired
   version number.  Do not push anything upstream at this point.

 * Run `make maintainer-distcheck'.  If there are any problems, fix them,
   run `git tag -d v<version>' and start again from the `git commit' step.

 * Run `make <target> PREV_VERSION=maj.min[.mic[alpha]]', with target set
   to `major', `alpha', or `beta' as appropriate.  This will run various
   additional checks and create diff and xdelta files from the previous
   version.

 * Run './build-aux/gnupload --to [dest].gnu.org:m4 [files]' to create
   detached gpg signature and clear signed directive files, and upload
   the combination to the correct location.  For an alpha release,
   gnupload will place files in alpha.gnu.org, in /incoming/alpha, and
   the xdelta file is not strictly necessary.  For a full release,
   gnupload will place files in ftp.gnu.org, in /incoming/ftp.  Verify
   that the files uploaded successfully before sending an announcement.

 * Send announcement to m4-discuss@gnu.org, m4-announce@gnu.org, and
   autotools-announce@gnu.org.  If not an alpha send to info-gnu@gnu.org
   as well.  Use /tmp/announce-m4-<version>, created during the above
   `make <target>' run, as a starting point.  Contact a list
   administrator for m4-announce in advance to ensure your post will make
   it through (the list is normally set to silently discard all posts,
   even from subscribers).

 * Update version number in configure.ac to next alpha number.
   See http://www.gnu.org/software/libtool/contribute.html for details of
   the numbering scheme.

 * Update NEWS, README, and ChangeLog to start the intra-release changes,
   and run `git commit'.  Then run `git push origin refs/tags/v<version>'
   to push the release tag and complete the release.

 * For non-alpha releases, update the webpages.  Run `make web-manual',
   then copy the contents of doc/manual into a CVS checkout of the M4
   manual repository.  Also edit m4.html before doing a CVS checkin.
     export CVS_RSH=ssh
     cvs -z3 -d:ext:<user>@cvs.savannah.gnu.org:/web/m4 co m4

 * Post a news blurb on https://savannah.gnu.org/projects/m4.

 * Update the Free Software Directory.  Checkout the CVS sources:
     cvs -d :pserver:anonymous@cvs.sv.gnu.org:/sources/directory \
       co directory/m4.txt
   After making edits, mail the diff to <bug-directory@gnu.org>.

 --
 Copyright (C) 2004, 2005, 2006, 2007, 2008 Free Software Foundation, Inc.

 The canonical source of this file is maintained with the
 GNU M4 package.  Report bugs to bug-m4@gnu.org.

 GNU M4 is free software: you can redistribute it and/or modify
 it under the terms of the GNU General Public License as published by
 the Free Software Foundation, either version 3 of the License, or
 (at your option) any later version.

 GNU M4 is distributed in the hope that it will be useful,
 but WITHOUT ANY WARRANTY; without even the implied warranty of
 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
 GNU General Public License for more details.

 You should have received a copy of the GNU General Public License
 along with this program.  If not, see <http://www.gnu.org/licenses/>.

 Local Variables:
 mode: text
 fill-column: 72
 End:
 vim:tw=72
	GNU M4
	******

	1. Introduction
	===============

	This file attempts to describe the processes we use to maintain M4,
	and is not part of a release distribution.


	2. Maintenance Notes
	====================

	* If you incorporate a change from somebody on the net:
	If it is a large change, you must make sure they have signed the
	appropriate paperwork, and be sure to add their name and email
	address to THANKS. AUTHORS is built from the FSF list of copyright
	assignments, on fencepost.gnu.org.

	* If somebody reports a new bug, write a test case, then mention his
	name in the ChangeLog entry.

	* 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.

	* Changes with user-visible effects must be mentioned in NEWS.

	* GNU Coding Standards should be followed:
	http://www.gnu.org/prep/standards/
	Additionally, while GNU M4 is not yet POSIX compliant, we are trying
	to get closer to it (although some design decisions state that POSIX
	compliance should only happen when POSIXLY_CORRECT is in the
	environment or the -G option was passed on the command line):
	http://www.opengroup.org/onlinepubs/009695399/utilities/m4.html


	3. Bootstrapping
	================

	* The master M4 repository is stored in git.

	* Before you can build from git, you need to bootstrap. This requires:
	- A pre-installed version of GNU M4 1.4.5 or later, built from a package
	- Autoconf 2.60 or later
	- Automake 1.10.1 or later
	- Help2man 1.29 or later
	- LZMA Utils 4.32 or later (from <http://tukaani.org/lzma/>)
	- Texinfo 4.8 or later
	- Any prerequisites of the above (such as perl, tex)
	- A git checkout of gnulib. A read-only copy of gnulib can be
	obtained by:
	git clone git://git.sv.gnu.org/gnulib.git
	or
	cvs -d:pserver:anonymous@pserver.git.sv.gnu.org:/srv/git/gnulib.git \
	co -d gnulib HEAD

	If you are a member of the savannah group for gnulib, a read-write
	copy can be obtained by:
	git clone <savannah-user>@git.sv.gnu.org:/srv/git/gnulib.git

	Note that none of these bootstrapping dependencies should be required
	by a distributed release.

	* M4 has an optional build dependency. In order to ensure that the
	dependency remains optional, you can avoid the library by using
	`./configure --without-libsigsegv-prefix'. In order to ensure that
	the dependency is still viable with the current code base, you should
	install:
	- Libsigsegv 2.6 or later

	* Either add the gnulib directory to your PATH, or run
	GNULIB_TOOL=path/to/gnulib/gnulib-tool ./bootstrap

	* When it is time for a release, it is a good idea to bootstrap with
	official releases of the autotools, rather than git builds, to reduce
	the pain of a user re-running bootstrap on the packaged M4. However,
	files installed by Automake should be updated to the latest version
	from their respective upstream source, rather than the version that
	shipped with the automake release.


	4. Test Suite
	=============

	* Use
	make check
	liberally, on as many platforms as you can. Use as many compilers and
	linkers you can.

	* For branch-1.6, the testsuite is generated from the documentation.
	All instances of @example in doc/m4.texinfo that are not preceeded by
	"@comment ignore" are turned into tests in the checks directory.


	5. Editing 'ChangeLog'
	======================

	* When in doubt, check that emacs can syntax-color properly in
	change-log-mode. And preferably use emacs 'C-x 4 a'
	(add-change-log-entry-other-window) to open ChangeLog with an
	appropriate new template.

	* If this change is by a different author, or on a different date to the
	last entry start a new entry at the top of the file with the format
	(note two spaces between each field):

	yyyy-mm-dd Name of Author <email@address>

	* If more than one person collaborated on the change, additional
	authors can be listed on subsequent lines, thus:

	yyyy-mm-dd Name of Main Author <email@address>,
	Name of Contributor <another@email.address>

	* Where a change author did not supply a copyright assignment, but the
	changes they submitted were sufficiently trivial to commit in any case
	(see the GCS for guidelines on this), then flag this against their
	name in the header, thus:

	yyyy-mm-dd Name of Author <email@address> (tiny change)

	* Preferably the next part should be a description of the overall
	purpose of the change, separated from the header by a blank line,
	indented by 1 tab, and filled at column 72. The last character of the
	description should be a colon, :.

	* Changes to each file come next. Each new file starts on a new line,
	indented by 1 tab and starting with an asterisk and a space. Multiple
	files can be listed here relative to $top_srcdir, and comma separated.
	Names of functions (or sections as appropriate) to which the change
	applies should be named inside parentheses and comma separated. If
	this goes beyond column 72, then parens should be closed and re-opened
	on the next line:

	* file, another/file, test/testcases/foo.test (func_foo)
	(func_bar, func_baz): Description of changes.

	* If the change does not apply to particular functions (or sections),
	the section list can be omitted:

	* file, another/file, test/testcases/foo.test: General changes.

	* If the changes are particular to certain architectures, they should be
	listed after the functions in square brackets:

	* file, another/file (func_foo) [linux, solaris]: Description of
	changes.

	* Subsequent changes in other files that are related to the same overall
	enhancement or bugfix should be listed concurrently, without blank
	lines. Always start a fresh line for a new file:

	* file, another/file (func_foo) [linux, solaris]: Description of
	changes.
	* doc/foo.texi (Invoking Foo): Document.
	* NEWS: Updated.

	* If the change is in response to a problem reported by someone other
	than the author, then credit them at the end of the description with:

	Reported by Reporter Name <email@address>.

	* See the GNU Coding Standards document for more details on ChangeLog
	formatting.


	6. Release Procedure
	====================

	* If you are an m4 maintainer, but have not yet registered your
	gpg public key and (preferred) email address with the FSF, 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.

	* 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-m4) for outstanding bug reports also in the list of
	pending moderation requests. This step is not strictly necessary, but
	helps, since by default, m4-announce rejects all posts, so you have to
	get an administrator to allow your announcement through.

	* Make sure you have wget installed.

	* Make sure you have a copy of xdelta installed, and a copy of the previous
	release tarball in the build directory.

	* Make sure you have GNU make installed.

	* Make sure you have an up-to-date version of help2man installed.

	* Make sure your locale is sane, e.g. by exporting LC_ALL=C.

	* Update the version number in NEWS and ChangeLog, and mention in README
	whether the release is stable. See
	http://www.gnu.org/software/libtool/contribute.html for details of the
	numbering scheme (M4 uses a similar scheme to libtool, although
	intra-release versions carry more information thanks to
	git-version-gen).

	* Run ./bootstrap.

	* Run ./configure (a VPATH build should work, but is less tested).

	* Run `make'. The file doc/m4.1 needs to exist for a distribution, and
	be up-to-date with m4 --help output, but `make dist' intentionally
	does not depend on running a built binary.

	* Run `git commit' from the source tree if there are any changes from
	the previous steps.

	* Run `git tag -s -m <version> -u <gpg_key> v<version>' with the desired
	version number. Do not push anything upstream at this point.

	* Run `make maintainer-distcheck'. If there are any problems, fix them,
	run `git tag -d v<version>' and start again from the `git commit' step.

	* Run `make <target> PREV_VERSION=maj.min[.mic[alpha]]', with target set
	to `major', `alpha', or `beta' as appropriate. This will run various
	additional checks and create diff and xdelta files from the previous
	version.

	* Run './build-aux/gnupload --to [dest].gnu.org:m4 [files]' to create
	detached gpg signature and clear signed directive files, and upload
	the combination to the correct location. For an alpha release,
	gnupload will place files in alpha.gnu.org, in /incoming/alpha, and
	the xdelta file is not strictly necessary. For a full release,
	gnupload will place files in ftp.gnu.org, in /incoming/ftp. Verify
	that the files uploaded successfully before sending an announcement.

	* Send announcement to m4-discuss@gnu.org, m4-announce@gnu.org, and
	autotools-announce@gnu.org. If not an alpha send to info-gnu@gnu.org
	as well. Use /tmp/announce-m4-<version>, created during the above
	`make <target>' run, as a starting point. Contact a list
	administrator for m4-announce in advance to ensure your post will make
	it through (the list is normally set to silently discard all posts,
	even from subscribers).

	* Update version number in configure.ac to next alpha number.
	See http://www.gnu.org/software/libtool/contribute.html for details of
	the numbering scheme.

	* Update NEWS, README, and ChangeLog to start the intra-release changes,
	and run `git commit'. Then run `git push origin refs/tags/v<version>'
	to push the release tag and complete the release.

	* For non-alpha releases, update the webpages. Run `make web-manual',
	then copy the contents of doc/manual into a CVS checkout of the M4
	manual repository. Also edit m4.html before doing a CVS checkin.
	export CVS_RSH=ssh
	cvs -z3 -d:ext:<user>@cvs.savannah.gnu.org:/web/m4 co m4

	* Post a news blurb on https://savannah.gnu.org/projects/m4.

	* Update the Free Software Directory. Checkout the CVS sources:
	cvs -d :pserver:anonymous@cvs.sv.gnu.org:/sources/directory \
	co directory/m4.txt
	After making edits, mail the diff to <bug-directory@gnu.org>.

	--
	Copyright (C) 2004, 2005, 2006, 2007, 2008 Free Software Foundation, Inc.

	The canonical source of this file is maintained with the
	GNU M4 package. Report bugs to bug-m4@gnu.org.

	GNU M4 is free software: you can redistribute it and/or modify
	it under the terms of the GNU General Public License as published by
	the Free Software Foundation, either version 3 of the License, or
	(at your option) any later version.

	GNU M4 is distributed in the hope that it will be useful,
	but WITHOUT ANY WARRANTY; without even the implied warranty of
	MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
	GNU General Public License for more details.

	You should have received a copy of the GNU General Public License
	along with this program. If not, see <http://www.gnu.org/licenses/>.

	Local Variables:
	mode: text
	fill-column: 72
	End:
	vim:tw=72