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.x 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
 225 7. Alpha release note template
 226 ==============================
 227
 228 To: m4-announce@gnu.org, m4-discuss@gnu.org, autotools-announce@gnu.org
 229 Subject: GNU M4 @VERSION@ released (alpha release).
 230
 231 The GNU M4 Team is pleased to announce alpha release @VERSION@ of GNU
 232 M4.
 233
 234 GNU `m4' is an implementation of the traditional Unix macro processor.
 235 It is mostly SVR4 compatible, although it has some extensions (for
 236 example, handling more than 9 positional parameters to macros).  `m4'
 237 also has built-in functions for including files, running shell commands,
 238 doing arithmetic, etc.  Autoconf needs GNU `m4' for generating
 239 `configure' scripts, but not for running them.
 240
 241 Here are the compressed sources:
 242
 243   ftp://alpha.gnu.org/gnu/m4/m4-@VERSION@.tar.gz    [@SIZE@]
 244   ftp://alpha.gnu.org/gnu/m4/m4-@VERSION@.tar.bz2   [@SIZE@]
 245
 246 Here are the xdeltas and diffs against m4-@PREV_RELEASE_VERSION_ON_THIS_BRANCH@:
 247
 248   ftp://alpha.gnu.org/gnu/m4/m4-@PREV_RELEASE_VERSION_ON_THIS_BRANCH@-@VERSION@.diff.gz   [@SIZE@]
 249   ftp://alpha.gnu.org/gnu/m4/m4-@PREV_RELEASE_VERSION_ON_THIS_BRANCH@-@VERSION@.xdelta    [@SIZE@]
 250
 251 Here are the gpg detached signatures:
 252
 253   ftp://alpha.gnu.org/gnu/m4/m4-@VERSION@.tar.gz.sig
 254   ftp://alpha.gnu.org/gnu/m4/m4-@VERSION@.tar.bz2.sig
 255   ftp://alpha.gnu.org/gnu/m4/m4-@PREV_RELEASE_VERSION_ON_THIS_BRANCH@-@VERSION@.diff.gz.sig
 256   ftp://alpha.gnu.org/gnu/m4/m4-@PREV_RELEASE_VERSION_ON_THIS_BRANCH@-@VERSION@.xdelta.sig
 257
 258 You should download the signature named after any tarball you download,
 259 and then verify its integrity with, for example:
 260
 261   gpg --verify m4-@VERSION@.tar.gz.sig
 262
 263 If that command fails because you don't have the required public key,
 264 then run this command to import it:
 265
 266   gpg --keyserver wwwkeys.pgp.net --recv-keys @KEY@
 267
 268 Here are the MD5 and SHA1 checksums:
 269
 270   @MD5SUM@ m4-@VERSION@.tar.gz
 271   @MD5SUM@ m4-@VERSION@.tar.bz2
 272   @MD5SUM@ m4-@PREV_RELEASE_VERSION_ON_THIS_BRANCH@-@VERSION@.diff.gz
 273   @MD5SUM@ m4-@PREV_RELEASE_VERSION_ON_THIS_BRANCH@-@VERSION@.xdelta
 274   @SHA1SUM@ m4-@VERSION@.tar.gz
 275   @SHA1SUM@ m4-@VERSION@.tar.bz2
 276   @SHA1SUM@ m4-@PREV_RELEASE_VERSION_ON_THIS_BRANCH@-@VERSION@.diff.gz
 277   @SHA1SUM@ m4-@PREV_RELEASE_VERSION_ON_THIS_BRANCH@-@VERSION@.xdelta
 278
 279 This release has @SUMMARY_OF_IMPROVEMENTS_SINCE_LAST_RELEASE_ON_THIS_BRANCH@.
 280
 281 This release was bootstrapped with @BOOTSTRAP_TOOLS_WITH_VERSIONS@.
 282
 283 Alternatively, you can fetch the unbootstrapped sourcecode from
 284 anonymous cvs by using the following commands:
 285
 286   $ export CVS_RSH=ssh
 287   $ cvs -z3 -d :pserver:anonymous@cvs.sv.gnu.org:/sources/m4 \
 288   co -r @CVS_RELEASE_TAG@ m4
 289
 290 You will then need to have recent versions of Automake and Autoconf
 291 installed, and a recent checkout of gnulib, in order to bootstrap the
 292 checked out sources yourself.
 293
 294 New in @VERSION@: @RELEASE_DATE@
 295
 296   @EXCERPT_FROM_NEWS_FILE@
 297
 298 Please report bugs to <bug-m4@gnu.org>, along with the output of 'make
 299 check' and any other information that might be useful in resolving the
 300 issue.
 301
 302
 303 8. Full release note template
 304 =============================
 305
 306 To: info-gnu@gnu.org
 307 To: m4-announce@gnu.org, m4-discuss@gnu.org, autotools-announce@gnu.org
 308 Subject: GNU M4 @VERSION@ released.
 309
 310 The GNU M4 Team is pleased to announce the release of GNU M4 @VERSION@.
 311
 312 GNU `m4' is an implementation of the traditional Unix macro processor.
 313 It is mostly SVR4 compatible, although it has some extensions (for
 314 example, handling more than 9 positional parameters to macros).  `m4'
 315 also has built-in functions for including files, running shell commands,
 316 doing arithmetic, etc.  Autoconf needs GNU `m4' for generating
 317 `configure' scripts, but not for running them.
 318
 319 This release has @SUMMARY_OF_IMPROVEMENTS_SINCE_LAST_RELEASE_ON_THIS_BRANCH@.
 320
 321 New in @VERSION@: @RELEASE_DATE@
 322
 323   @EXCERPT_FROM_NEWS_FILE@
 324
 325 m4-@VERSION@ is available now from ftp.gnu.org, along with diffs and
 326 xdeltas against m4-@PREV_RELEASE_VERSION_ON_THIS_BRANCH@ that are also
 327 available from ftp.gnu.org.  Please use a mirror to reduce stress on the
 328 main gnu machine:
 329
 330   http://www.gnu.org/order/ftp.html
 331
 332 Here are the compressed sources:
 333
 334   ftp://ftp.gnu.org/gnu/m4/m4-@VERSION@.tar.gz    [@SIZE@]
 335   ftp://ftp.gnu.org/gnu/m4/m4-@VERSION@.tar.bz2   [@SIZE@]
 336
 337 Here are the xdeltas and diffs against m4-@PREV_RELEASE_VERSION_ON_THIS_BRANCH@:
 338
 339   ftp://ftp.gnu.org/gnu/m4/m4-@PREV_RELEASE_VERSION_ON_THIS_BRANCH@-@VERSION@.diff.gz   [@SIZE@]
 340   ftp://ftp.gnu.org/gnu/m4/m4-@PREV_RELEASE_VERSION_ON_THIS_BRANCH@-@VERSION@.xdelta    [@SIZE@]
 341
 342 Here are the gpg detached signatures:
 343
 344   ftp://ftp.gnu.org/gnu/m4/m4-@VERSION@.tar.gz.sig
 345   ftp://ftp.gnu.org/gnu/m4/m4-@VERSION@.tar.bz2.sig
 346   ftp://ftp.gnu.org/gnu/m4/m4-@PREV_RELEASE_VERSION_ON_THIS_BRANCH@-@VERSION@.diff.gz.sig
 347   ftp://ftp.gnu.org/gnu/m4/m4-@PREV_RELEASE_VERSION_ON_THIS_BRANCH@-@VERSION@.xdelta.sig
 348
 349 You should download the signature named after any tarball you download,
 350 and then verify its integrity with, for example:
 351
 352   gpg --verify m4-@VERSION@.tar.gz.sig
 353
 354 If that command fails because you don't have the required public key,
 355 then run this command to import it:
 356
 357   gpg --keyserver wwwkeys.pgp.net --recv-keys @KEY@
 358
 359 Here are the MD5 and SHA1 checksums:
 360
 361   @MD5SUM@ m4-@VERSION@.tar.gz
 362   @MD5SUM@ m4-@VERSION@.tar.bz2
 363   @MD5SUM@ m4-@PREV_RELEASE_VERSION_ON_THIS_BRANCH@-@VERSION@.diff.gz
 364   @MD5SUM@ m4-@PREV_RELEASE_VERSION_ON_THIS_BRANCH@-@VERSION@.xdelta
 365   @SHA1SUM@ m4-@VERSION@.tar.gz
 366   @SHA1SUM@ m4-@VERSION@.tar.bz2
 367   @SHA1SUM@ m4-@PREV_RELEASE_VERSION_ON_THIS_BRANCH@-@VERSION@.diff.gz
 368   @SHA1SUM@ m4-@PREV_RELEASE_VERSION_ON_THIS_BRANCH@-@VERSION@.xdelta
 369
 370 This release was bootstrapped with @BOOTSTRAP_TOOLS_WITH_VERSIONS@.
 371
 372 Alternatively, you can fetch the unbootstrapped sourcecode from
 373 anonymous cvs by using the following commands:
 374
 375   $ export CVS_RSH=ssh
 376   $ cvs -z3 -d :pserver:anonymous@cvs.sv.gnu.org:/sources/m4 \
 377   co -r @CVS_RELEASE_TAG@ m4
 378
 379 You will then need to have the latest release versions of Automake
 380 (@AUTOMAKE_VERSION@) and Autoconf (@AUTOCONF_VERSION@) installed to
 381 bootstrap the checked out sources yourself.
 382
 383 Please report bugs to <bug-m4@gnu.org>, along with the output of 'make
 384 check' and any other information that might be useful in resolving the
 385 issue.
 386
 387
 388 --
 389 Copyright (C) 2004, 2005, 2006 Free Software Foundation, Inc.
 390
 391 The canonical source of this file is maintained with the
 392 GNU M4 package.  Report bugs to bug-m4@gnu.org.
 393
 394 GNU M4 is free software; you can redistribute it and/or
 395 modify it under the terms of the GNU General Public License as
 396 published by the Free Software Foundation; either version 2
 397 of the License, or (at your option) any later version.
 398
 399 GNU M4 is distributed in the hope that it will be useful,
 400 but WITHOUT ANY WARRANTY; without even the implied warranty of
 401 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
 402 General Public License for more details.
 403
 404 You should have received a copy of the GNU General Public License
 405 along with GNU M4; if not, write to the Free Software
 406 Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA
 407 02110-1301  USA
 408
 409
 410 Local Variables:
 411 mode: text
 412 fill-column: 72
 413 End:
 414 vim:tw=72