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