m4/HACKING

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.

* New macros must be blind, or else prefixed with `m4' or `__', in
  order to minimize backward compatibility issues with previous
  releases of M4 when processing English text.

* 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

* Except for third-party files (libtool, gnulib, ...), all .c files
  should #include <config.h> before anything else (since there are some
  #defines in config.h that potentially impact system headers, such as
  when the user does ./configure --disable-assert).  This means that no
  .h files need to #include <config.h>.  However, users compiling
  external modules should be able to compile without <config.h>, since
  <config.h> is specific to the M4 build and is not installable.


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

* The master M4 repository is stored in git.  You can obtain a read-only
  copy with:
    git clone git://git.sv.gnu.org/m4.git
  or
    cvs -d:pserver:anonymous@pserver.git.sv.gnu.org:/srv/git/m4.git \
      co -d m4 HEAD

  If you are a member of the savannah group for M4, a read-write
  copy can be obtained by:
    git clone <savannah-user>@git.sv.gnu.org:/srv/git/m4.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 (recommend 1.4.11 or later)
  - Autoconf 2.62 or later
  - Automake 1.10.1 or later
  - Libtool 2.2 or later
  - Gettext 0.16 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.

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

* Some of 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 tests 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.

* 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 your locale is sane, e.g. by exporting LC_ALL=C.

* Update the version number in configure.ac.
  See http://www.gnu.org/software/libtool/contribute.html for details of
  the numbering scheme (m4 uses the same scheme as libtool).

* Update NEWS, ChangeLog.

* Run ./bootstrap.

* Run ./configure (or create a build directory first and run configure
  from there, if you want to keep the build tree separate).

* Run `make distcheck'.  If there are any problems, fix them and start
  again.

* Run ./commit from the source tree.

* TODO - adjust this step to account for git:
  Run `make cvs-dist', which will build a release tarball (with `make
  distcheck') and tag the tree with release-$(VERSION).

* Run 'make deltas' (pass LASTRELEASE=maj.min[.mic[alpha]] if needed) to
  create both diff and xdelta files between the previous release tarball
  and the new.  TODO - is xdelta still worth using?

* Run '[../]./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.

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

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

* Run ./commit.

* For non-alpha releases, update the webpages.  Replace manual.html with
  the new one (generate with `make web-manual').

* Update the M4 entry in the GNU Software directory, located at
  http://directory.fsf.org/GNU/gnum4.html.  To do this, check out the
  directory template:
    cvs -z3 -d:pserver:anonymous@cvs.sv.gnu.org:/sources/directory \
       co directory/gnum4.txt
  then mail the patch to bug-directory@gnu.org.


7. Alpha release note template
==============================

To: m4-announce@gnu.org, m4-discuss@gnu.org, autotools-announce@gnu.org
Subject: GNU M4 @VERSION@ released (alpha release).

The GNU M4 Team is pleased to announce alpha release @VERSION@ of GNU
M4.

GNU `m4' is an implementation of the traditional Unix macro processor.
It is mostly SVR4 compatible, although it has some extensions (for
example, handling more than 9 positional parameters to macros).  `m4'
also has built-in functions for including files, running shell commands,
doing arithmetic, etc.  Autoconf needs GNU `m4' for generating
`configure' scripts, but not for running them.

Here are the compressed sources:

  ftp://alpha.gnu.org/gnu/m4/m4-@VERSION@.tar.gz    [@SIZE@]
  ftp://alpha.gnu.org/gnu/m4/m4-@VERSION@.tar.bz2   [@SIZE@]

Here are the xdeltas and diffs against m4-@PREV_RELEASE_VERSION_ON_THIS_BRANCH@:

  ftp://alpha.gnu.org/gnu/m4/m4-@PREV_RELEASE_VERSION_ON_THIS_BRANCH@-@VERSION@.diff.gz   [@SIZE@]
  ftp://alpha.gnu.org/gnu/m4/m4-@PREV_RELEASE_VERSION_ON_THIS_BRANCH@-@VERSION@.xdelta    [@SIZE@]

Here are the gpg detached signatures:

  ftp://alpha.gnu.org/gnu/m4/m4-@VERSION@.tar.gz.sig
  ftp://alpha.gnu.org/gnu/m4/m4-@VERSION@.tar.bz2.sig
  ftp://alpha.gnu.org/gnu/m4/m4-@PREV_RELEASE_VERSION_ON_THIS_BRANCH@-@VERSION@.diff.gz.sig
  ftp://alpha.gnu.org/gnu/m4/m4-@PREV_RELEASE_VERSION_ON_THIS_BRANCH@-@VERSION@.xdelta.sig

You should download the signature named after any tarball you download,
and then verify its integrity with, for example:

  gpg --verify m4-@VERSION@.tar.gz.sig

If that command fails because you don't have the required public key,
then run this command to import it:

  gpg --keyserver wwwkeys.pgp.net --recv-keys @KEY@

Here are the MD5 and SHA1 checksums:

  @MD5SUM@ m4-@VERSION@.tar.gz
  @MD5SUM@ m4-@VERSION@.tar.bz2
  @MD5SUM@ m4-@PREV_RELEASE_VERSION_ON_THIS_BRANCH@-@VERSION@.diff.gz
  @MD5SUM@ m4-@PREV_RELEASE_VERSION_ON_THIS_BRANCH@-@VERSION@.xdelta
  @SHA1SUM@ m4-@VERSION@.tar.gz
  @SHA1SUM@ m4-@VERSION@.tar.bz2
  @SHA1SUM@ m4-@PREV_RELEASE_VERSION_ON_THIS_BRANCH@-@VERSION@.diff.gz
  @SHA1SUM@ m4-@PREV_RELEASE_VERSION_ON_THIS_BRANCH@-@VERSION@.xdelta

This release has @SUMMARY_OF_IMPROVEMENTS_SINCE_LAST_RELEASE_ON_THIS_BRANCH@.

This release was bootstrapped with @BOOTSTRAP_TOOLS_WITH_VERSIONS@.

Alternatively, you can fetch the unbootstrapped sourcecode from git by
using the following commands:

  $ git clone git://git.sv.gnu.org/m4
  $ git checkout -b branch @GIT_RELEASE_TAG@

You will then need to have recent versions of Automake and Autoconf
installed, and a recent checkout of gnulib, in order to bootstrap the
checked out sources yourself.

New in @VERSION@: @RELEASE_DATE@

  @EXCERPT_FROM_NEWS_FILE@

Please report bugs to <bug-m4@gnu.org>, along with the output of 'make
check' and any other information that might be useful in resolving the
issue.


8. Full release note template
=============================

To: info-gnu@gnu.org
To: m4-announce@gnu.org, m4-discuss@gnu.org, autotools-announce@gnu.org
Subject: GNU M4 @VERSION@ released.

The GNU M4 Team is pleased to announce the release of GNU M4 @VERSION@.

GNU `m4' is an implementation of the traditional Unix macro processor.
It is mostly SVR4 compatible, although it has some extensions (for
example, handling more than 9 positional parameters to macros).  `m4'
also has built-in functions for including files, running shell commands,
doing arithmetic, etc.  Autoconf needs GNU `m4' for generating
`configure' scripts, but not for running them.

This release has @SUMMARY_OF_IMPROVEMENTS_SINCE_LAST_RELEASE_ON_THIS_BRANCH@.

New in @VERSION@: @RELEASE_DATE@

  @EXCERPT_FROM_NEWS_FILE@

m4-@VERSION@ is available now from ftp.gnu.org, along with diffs and
xdeltas against m4-@PREV_RELEASE_VERSION_ON_THIS_BRANCH@ that are also
available from ftp.gnu.org.  Please use a mirror to reduce stress on the
main gnu machine:

  http://www.gnu.org/order/ftp.html

Here are the compressed sources:

  ftp://ftp.gnu.org/gnu/m4/m4-@VERSION@.tar.gz    [@SIZE@]
  ftp://ftp.gnu.org/gnu/m4/m4-@VERSION@.tar.bz2   [@SIZE@]

Here are the xdeltas and diffs against m4-@PREV_RELEASE_VERSION_ON_THIS_BRANCH@:

  ftp://ftp.gnu.org/gnu/m4/m4-@PREV_RELEASE_VERSION_ON_THIS_BRANCH@-@VERSION@.diff.gz   [@SIZE@]
  ftp://ftp.gnu.org/gnu/m4/m4-@PREV_RELEASE_VERSION_ON_THIS_BRANCH@-@VERSION@.xdelta    [@SIZE@]

Here are the gpg detached signatures:

  ftp://ftp.gnu.org/gnu/m4/m4-@VERSION@.tar.gz.sig
  ftp://ftp.gnu.org/gnu/m4/m4-@VERSION@.tar.bz2.sig
  ftp://ftp.gnu.org/gnu/m4/m4-@PREV_RELEASE_VERSION_ON_THIS_BRANCH@-@VERSION@.diff.gz.sig
  ftp://ftp.gnu.org/gnu/m4/m4-@PREV_RELEASE_VERSION_ON_THIS_BRANCH@-@VERSION@.xdelta.sig

You should download the signature named after any tarball you download,
and then verify its integrity with, for example:

  gpg --verify m4-@VERSION@.tar.gz.sig

If that command fails because you don't have the required public key,
then run this command to import it:

  gpg --keyserver wwwkeys.pgp.net --recv-keys @KEY@

Here are the MD5 and SHA1 checksums:

  @MD5SUM@ m4-@VERSION@.tar.gz
  @MD5SUM@ m4-@VERSION@.tar.bz2
  @MD5SUM@ m4-@PREV_RELEASE_VERSION_ON_THIS_BRANCH@-@VERSION@.diff.gz
  @MD5SUM@ m4-@PREV_RELEASE_VERSION_ON_THIS_BRANCH@-@VERSION@.xdelta
  @SHA1SUM@ m4-@VERSION@.tar.gz
  @SHA1SUM@ m4-@VERSION@.tar.bz2
  @SHA1SUM@ m4-@PREV_RELEASE_VERSION_ON_THIS_BRANCH@-@VERSION@.diff.gz
  @SHA1SUM@ m4-@PREV_RELEASE_VERSION_ON_THIS_BRANCH@-@VERSION@.xdelta

This release was bootstrapped with @BOOTSTRAP_TOOLS_WITH_VERSIONS@.

Alternatively, you can fetch the unbootstrapped sourcecode from git by
using the following commands:

  $ git clone git://git.sv.gnu.org/m4
  $ git checkout -b branch @GIT_RELEASE_TAG@

You will then need to have the latest release versions of Automake
(@AUTOMAKE_VERSION@) and Autoconf (@AUTOCONF_VERSION@) installed, as
well as a git checkout of gnulib, in order to bootstrap the checked out
sources yourself.

Please report bugs to <bug-m4@gnu.org>, along with the output of 'make
check' and any other information that might be useful in resolving the
issue.


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