HACKING

   1 GNU M4
   2 ******
   3
   4 1. Introduction
   5 ===============
   6
   7 This file attempts to describe the processes we use to maintain M4,
   8 and is not part of a release distribution.
   9
  10
  11 2. Maintenance Notes
  12 ====================
  13
  14 * If you incorporate a change from somebody on the net:
  15   If it is a large change, you must make sure they have signed the
  16   appropriate paperwork, and be sure to add their name and email
  17   address to THANKS.  AUTHORS is built from the FSF list of copyright
  18   assignments, on fencepost.gnu.org.
  19
  20 * If somebody reports a new bug, write a test case, then mention his
  21   name in the ChangeLog entry.
  22
  23 * The correct response to most actual bugs is to write a new test case
  24   which demonstrates the bug.  Then fix the bug, re-run the test suite,
  25   and check everything in.
  26
  27 * Changes with user-visible effects must be mentioned in NEWS.
  28
  29 * New macros must be blind, or else prefixed with `m4' or `__', in
  30   order to minimize backward compatibility issues with previous
  31   releases of M4 when processing English text.
  32
  33 * GNU Coding Standards should be followed:
  34     http://www.gnu.org/prep/standards/
  35   Additionally, while GNU M4 is not yet POSIX compliant, we are trying
  36   to get closer to it (although some design decisions state that POSIX
  37   compliance should only happen when POSIXLY_CORRECT is in the
  38   environment or the -G option was passed on the command line):
  39     http://www.opengroup.org/onlinepubs/009695399/utilities/m4.html
  40
  41
  42 3. Bootstrapping
  43 ================
  44
  45 * Before you can build from CVS, you need to bootstrap.  This requires a
  46   pre-installed version of GNU M4 1.4.5 or later, built from a package;
  47   Autoconf 2.60 or later; Automake 1.10a or later; CVS Head of Libtool
  48   (will become Libtool 2.0); Gettext 0.16 or later; and a CVS checkout
  49   of gnulib.  Gnulib can be obtained by:
  50     cvs -z3 -d:pserver:anonymous@cvs.sv.gnu.org:/sources/gnulib co gnulib
  51
  52 * Either add the gnulib directory to your PATH, or run
  53     GNULIB_TOOL=path/to/gnulib/gnulib-tool ./bootstrap
  54
  55 * When it is time for a release, it is a good idea to bootstrap with
  56   official releases of the autotools, rather than CVS builds, to reduce
  57   the pain of a user re-running bootstrap on the packaged M4.  However,
  58   files installed by Automake should be updated to the latest version
  59   from their respective upstream source, rather than the version that
  60   shipped with the automake release.
  61
  62
  63 4. Test Suite
  64 =============
  65
  66 * Use
  67     make check
  68   liberally, on as many platforms as you can.  Use as many compilers and
  69   linkers you can.
  70
  71 * Some of the testsuite is generated from the documentation.
  72   All instances of @example in doc/m4.texinfo that are not preceeded by
  73   "@comment ignore" are turned into tests in the tests directory.
  74
  75
  76 5. Editing 'ChangeLog'
  77 ======================
  78
  79 * When in doubt, check that emacs can syntax-color properly in
  80   change-log-mode.  And preferably use emacs 'C-x 4 a'
  81   (add-change-log-entry-other-window) to open ChangeLog with an
  82   appropriate new template.
  83
  84 * If this change is by a different author, or on a different date to the
  85   last entry start a new entry at the top of the file with the format
  86   (note two spaces between each field):
  87
  88 yyyy-mm-dd  Name of Author  <email@address>
  89
  90 *  If more than one person collaborated on the change, additional
  91    authors can be listed on subsequent lines, thus:
  92
  93 yyyy-mm-dd  Name of Main Author  <email@address>,
  94             Name of Contributor  <another@email.address>
  95
  96 * Where a change author did not supply a copyright assignment, but the
  97   changes they submitted were sufficiently trivial to commit in any case
  98   (see the GCS for guidelines on this), then flag this against their
  99   name in the header, thus:
 100
 101 yyyy-mm-dd  Name of Author  <email@address>  (tiny change)
 102
 103 * Preferably the next part should be a description of the overall
 104   purpose of the change, separated from the header by a blank line,
 105   indented by 1 tab, and filled at column 72.  The last character of the
 106   description should be a colon, :.
 107
 108 * Changes to each file come next.  Each new file starts on a new line,
 109   indented by 1 tab and starting with an asterisk and a space.  Multiple
 110   files can be listed here relative to $top_srcdir, and comma separated.
 111   Names of functions (or sections as appropriate) to which the change
 112   applies should be named inside parentheses and comma separated.  If
 113   this goes beyond column 72, then parens should be closed and re-opened
 114   on the next line:
 115
 116         * file, another/file, test/testcases/foo.test (func_foo)
 117         (func_bar, func_baz): Description of changes.
 118
 119 * If the change does not apply to particular functions (or sections),
 120   the section list can be omitted:
 121
 122         * file, another/file, test/testcases/foo.test: General changes.
 123
 124 * If the changes are particular to certain architectures, they should be
 125   listed after the functions in square brackets:
 126
 127         * file, another/file (func_foo) [linux, solaris]: Description of
 128         changes.
 129
 130 * Subsequent changes in other files that are related to the same overall
 131   enhancement or bugfix should be listed concurrently, without blank
 132   lines.  Always start a fresh line for a new file:
 133
 134         * file, another/file (func_foo) [linux, solaris]: Description of
 135         changes.
 136         * doc/foo.texi (Invoking Foo): Document.
 137         * NEWS: Updated.
 138
 139 * If the change is in response to a problem reported by someone other
 140   than the author, then credit them at the end of the description with:
 141
 142         Reported by Reporter Name <email@address>.
 143
 144 * See the GNU Coding Standards document for more details on ChangeLog
 145   formatting.
 146
 147
 148 6. Release Procedure
 149 ====================
 150
 151 * If you are an m4 maintainer, but have not yet registered your
 152   gpg public key and (preferred) email address with the FSF, send an
 153   email, preferably GPG-signed, to <ftp-upload@gnu.org> that includes
 154   the following:
 155
 156     (a) name of package(s) that you are the maintainer for, and your
 157         preferred email address.
 158
 159     (b) an ASCII armored copy of your GnuPG key, as an attachment.
 160         ("gpg --export -a YOUR_KEY_ID > mykey.asc" should give you
 161         this.)
 162
 163   When you have received acknowledgement of your message, the proper GPG
 164   keys will be registered on ftp-upload.gnu.org and only then will you be
 165   authorized to upload files to the FSF ftp machines.
 166
 167 * If you do not have access to the mailing list administrative interface,
 168   approach the list owners for the password.  Be sure to check the lists
 169   (esp. bug-m4) for outstanding bug reports also in the list of
 170   pending moderation requests.  This step is not strictly necessary.
 171
 172 * Make sure you have wget installed.
 173
 174 * Make sure you have a copy of xdelta installed, and a copy of the previous
 175   release tarball in the build directory.
 176
 177 * Make sure your locale is sane, e.g. by exporting LC_ALL=C.
 178
 179 * Update the version number in configure.ac.
 180   See http://www.gnu.org/software/libtool/contribute.html for details of
 181   the numbering scheme (m4 uses the same scheme as libtool).
 182
 183 * Update NEWS, ChangeLog.
 184
 185 * Run ./bootstrap.
 186
 187 * Run ./configure (or create a build directory first and run configure
 188   from there, if you want to keep the build tree separate).
 189
 190 * Run `make distcheck'.  If there are any problems, fix them and start
 191   again.
 192
 193 * Run ./commit from the source tree.
 194
 195 * Run `make cvs-dist', which will build a release tarball (with `make
 196   distcheck'), and tag the tree with release-$(VERSION).
 197
 198 * Run 'make deltas' (pass LASTRELEASE=maj.min[.mic[alpha]] if needed) to
 199   create both diff and xdelta files between the previous release tarball
 200   and the new.
 201
 202 * Run '[../]./gnupload --to [dest].gnu.org:m4 [files]' to create
 203   detached gpg signature and clear signed directive files, and upload
 204   the combination to the correct location.  For an alpha release,
 205   gnupload will place files in alpha.gnu.org, in /incoming/alpha, and
 206   the xdelta file is not strictly necessary.  For a full release,
 207   gnupload will place files in ftp.gnu.org, in /incoming/ftp.
 208
 209 * Send announcement to m4-discuss@gnu.org, m4-announce@gnu.org, and
 210   autotools-announce@gnu.org.  If not an alpha send to info-gnu@gnu.org
 211   as well.
 212
 213 * Update version number in configure.ac to next alpha number.
 214   See http://www.gnu.org/software/libtool/contribute.html for details of
 215   the numbering scheme.
 216
 217 * Update NEWS, ChangeLog.
 218
 219 * Run ./commit.
 220
 221 * For non-alpha releases, update the webpages.  Replace manual.html with
 222   the new one (generate with `make web-manual').
 223
 224 * Update the M4 entry in the GNU Software directory, located at
 225   http://directory.fsf.org/GNU/gnum4.html.  To do this, check out the
 226   directory template:
 227     cvs -z3 -d:pserver:anonymous@cvs.sv.gnu.org:/sources/directory \
 228        co directory/gnum4.txt
 229   then mail the patch to bug-directory@gnu.org.
 230
 231
 232 7. Alpha release note template
 233 ==============================
 234
 235 To: m4-announce@gnu.org, m4-discuss@gnu.org, autotools-announce@gnu.org
 236 Subject: GNU M4 @VERSION@ released (alpha release).
 237
 238 The GNU M4 Team is pleased to announce alpha release @VERSION@ of GNU
 239 M4.
 240
 241 GNU `m4' is an implementation of the traditional Unix macro processor.
 242 It is mostly SVR4 compatible, although it has some extensions (for
 243 example, handling more than 9 positional parameters to macros).  `m4'
 244 also has built-in functions for including files, running shell commands,
 245 doing arithmetic, etc.  Autoconf needs GNU `m4' for generating
 246 `configure' scripts, but not for running them.
 247
 248 Here are the compressed sources:
 249
 250   ftp://alpha.gnu.org/gnu/m4/m4-@VERSION@.tar.gz    [@SIZE@]
 251   ftp://alpha.gnu.org/gnu/m4/m4-@VERSION@.tar.bz2   [@SIZE@]
 252
 253 Here are the xdeltas and diffs against m4-@PREV_RELEASE_VERSION_ON_THIS_BRANCH@:
 254
 255   ftp://alpha.gnu.org/gnu/m4/m4-@PREV_RELEASE_VERSION_ON_THIS_BRANCH@-@VERSION@.diff.gz   [@SIZE@]
 256   ftp://alpha.gnu.org/gnu/m4/m4-@PREV_RELEASE_VERSION_ON_THIS_BRANCH@-@VERSION@.xdelta    [@SIZE@]
 257
 258 Here are the gpg detached signatures:
 259
 260   ftp://alpha.gnu.org/gnu/m4/m4-@VERSION@.tar.gz.sig
 261   ftp://alpha.gnu.org/gnu/m4/m4-@VERSION@.tar.bz2.sig
 262   ftp://alpha.gnu.org/gnu/m4/m4-@PREV_RELEASE_VERSION_ON_THIS_BRANCH@-@VERSION@.diff.gz.sig
 263   ftp://alpha.gnu.org/gnu/m4/m4-@PREV_RELEASE_VERSION_ON_THIS_BRANCH@-@VERSION@.xdelta.sig
 264
 265 You should download the signature named after any tarball you download,
 266 and then verify its integrity with, for example:
 267
 268   gpg --verify m4-@VERSION@.tar.gz.sig
 269
 270 If that command fails because you don't have the required public key,
 271 then run this command to import it:
 272
 273   gpg --keyserver wwwkeys.pgp.net --recv-keys @KEY@
 274
 275 Here are the MD5 and SHA1 checksums:
 276
 277   @MD5SUM@ m4-@VERSION@.tar.gz
 278   @MD5SUM@ m4-@VERSION@.tar.bz2
 279   @MD5SUM@ m4-@PREV_RELEASE_VERSION_ON_THIS_BRANCH@-@VERSION@.diff.gz
 280   @MD5SUM@ m4-@PREV_RELEASE_VERSION_ON_THIS_BRANCH@-@VERSION@.xdelta
 281   @SHA1SUM@ m4-@VERSION@.tar.gz
 282   @SHA1SUM@ m4-@VERSION@.tar.bz2
 283   @SHA1SUM@ m4-@PREV_RELEASE_VERSION_ON_THIS_BRANCH@-@VERSION@.diff.gz
 284   @SHA1SUM@ m4-@PREV_RELEASE_VERSION_ON_THIS_BRANCH@-@VERSION@.xdelta
 285
 286 This release has @SUMMARY_OF_IMPROVEMENTS_SINCE_LAST_RELEASE_ON_THIS_BRANCH@.
 287
 288 This release was bootstrapped with @BOOTSTRAP_TOOLS_WITH_VERSIONS@.
 289
 290 Alternatively, you can fetch the unbootstrapped sourcecode from
 291 anonymous cvs by using the following commands:
 292
 293   $ export CVS_RSH=ssh
 294   $ cvs -z3 -d :pserver:anonymous@cvs.sv.gnu.org:/sources/m4 \
 295   co -r @CVS_RELEASE_TAG@ m4
 296
 297 You will then need to have recent versions of Automake and Autoconf
 298 installed, and a recent checkout of gnulib, in order to bootstrap the
 299 checked out sources yourself.
 300
 301 New in @VERSION@: @RELEASE_DATE@
 302
 303   @EXCERPT_FROM_NEWS_FILE@
 304
 305 Please report bugs to <bug-m4@gnu.org>, along with the output of 'make
 306 check' and any other information that might be useful in resolving the
 307 issue.
 308
 309
 310 8. Full release note template
 311 =============================
 312
 313 To: info-gnu@gnu.org
 314 To: m4-announce@gnu.org, m4-discuss@gnu.org, autotools-announce@gnu.org
 315 Subject: GNU M4 @VERSION@ released.
 316
 317 The GNU M4 Team is pleased to announce the release of GNU M4 @VERSION@.
 318
 319 GNU `m4' is an implementation of the traditional Unix macro processor.
 320 It is mostly SVR4 compatible, although it has some extensions (for
 321 example, handling more than 9 positional parameters to macros).  `m4'
 322 also has built-in functions for including files, running shell commands,
 323 doing arithmetic, etc.  Autoconf needs GNU `m4' for generating
 324 `configure' scripts, but not for running them.
 325
 326 This release has @SUMMARY_OF_IMPROVEMENTS_SINCE_LAST_RELEASE_ON_THIS_BRANCH@.
 327
 328 New in @VERSION@: @RELEASE_DATE@
 329
 330   @EXCERPT_FROM_NEWS_FILE@
 331
 332 m4-@VERSION@ is available now from ftp.gnu.org, along with diffs and
 333 xdeltas against m4-@PREV_RELEASE_VERSION_ON_THIS_BRANCH@ that are also
 334 available from ftp.gnu.org.  Please use a mirror to reduce stress on the
 335 main gnu machine:
 336
 337   http://www.gnu.org/order/ftp.html
 338
 339 Here are the compressed sources:
 340
 341   ftp://ftp.gnu.org/gnu/m4/m4-@VERSION@.tar.gz    [@SIZE@]
 342   ftp://ftp.gnu.org/gnu/m4/m4-@VERSION@.tar.bz2   [@SIZE@]
 343
 344 Here are the xdeltas and diffs against m4-@PREV_RELEASE_VERSION_ON_THIS_BRANCH@:
 345
 346   ftp://ftp.gnu.org/gnu/m4/m4-@PREV_RELEASE_VERSION_ON_THIS_BRANCH@-@VERSION@.diff.gz   [@SIZE@]
 347   ftp://ftp.gnu.org/gnu/m4/m4-@PREV_RELEASE_VERSION_ON_THIS_BRANCH@-@VERSION@.xdelta    [@SIZE@]
 348
 349 Here are the gpg detached signatures:
 350
 351   ftp://ftp.gnu.org/gnu/m4/m4-@VERSION@.tar.gz.sig
 352   ftp://ftp.gnu.org/gnu/m4/m4-@VERSION@.tar.bz2.sig
 353   ftp://ftp.gnu.org/gnu/m4/m4-@PREV_RELEASE_VERSION_ON_THIS_BRANCH@-@VERSION@.diff.gz.sig
 354   ftp://ftp.gnu.org/gnu/m4/m4-@PREV_RELEASE_VERSION_ON_THIS_BRANCH@-@VERSION@.xdelta.sig
 355
 356 You should download the signature named after any tarball you download,
 357 and then verify its integrity with, for example:
 358
 359   gpg --verify m4-@VERSION@.tar.gz.sig
 360
 361 If that command fails because you don't have the required public key,
 362 then run this command to import it:
 363
 364   gpg --keyserver wwwkeys.pgp.net --recv-keys @KEY@
 365
 366 Here are the MD5 and SHA1 checksums:
 367
 368   @MD5SUM@ m4-@VERSION@.tar.gz
 369   @MD5SUM@ m4-@VERSION@.tar.bz2
 370   @MD5SUM@ m4-@PREV_RELEASE_VERSION_ON_THIS_BRANCH@-@VERSION@.diff.gz
 371   @MD5SUM@ m4-@PREV_RELEASE_VERSION_ON_THIS_BRANCH@-@VERSION@.xdelta
 372   @SHA1SUM@ m4-@VERSION@.tar.gz
 373   @SHA1SUM@ m4-@VERSION@.tar.bz2
 374   @SHA1SUM@ m4-@PREV_RELEASE_VERSION_ON_THIS_BRANCH@-@VERSION@.diff.gz
 375   @SHA1SUM@ m4-@PREV_RELEASE_VERSION_ON_THIS_BRANCH@-@VERSION@.xdelta
 376
 377 This release was bootstrapped with @BOOTSTRAP_TOOLS_WITH_VERSIONS@.
 378
 379 Alternatively, you can fetch the unbootstrapped sourcecode from
 380 anonymous cvs by using the following commands:
 381
 382   $ export CVS_RSH=ssh
 383   $ cvs -z3 -d :pserver:anonymous@cvs.sv.gnu.org:/sources/m4 \
 384   co -r @CVS_RELEASE_TAG@ m4
 385
 386 You will then need to have the latest release versions of Automake
 387 (@AUTOMAKE_VERSION@) and Autoconf (@AUTOCONF_VERSION@) installed to
 388 bootstrap the checked out sources yourself.
 389
 390 Please report bugs to <bug-m4@gnu.org>, along with the output of 'make
 391 check' and any other information that might be useful in resolving the
 392 issue.
 393
 394
 395 --
 396 Copyright (C) 2004, 2005, 2006 Free Software Foundation, Inc.
 397
 398 The canonical source of this file is maintained with the
 399 GNU M4 package.  Report bugs to bug-m4@gnu.org.
 400
 401 GNU M4 is free software; you can redistribute it and/or
 402 modify it under the terms of the GNU General Public License as
 403 published by the Free Software Foundation; either version 2
 404 of the License, or (at your option) any later version.
 405
 406 GNU M4 is distributed in the hope that it will be useful,
 407 but WITHOUT ANY WARRANTY; without even the implied warranty of
 408 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
 409 General Public License for more details.
 410
 411 You should have received a copy of the GNU General Public License
 412 along with GNU M4; if not, write to the Free Software
 413 Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA
 414 02110-1301  USA
 415
 416
 417 Local Variables:
 418 mode: text
 419 fill-column: 72
 420 End:
 421 vim:tw=72