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, but
 166   helps, since by default, m4-announce rejects all posts, so you have to
 167   get an administrator to allow your announcement through.
 168
 169 * Make sure you have wget installed.
 170
 171 * Make sure you have a copy of xdelta installed, and a copy of the previous
 172   release tarball in the build directory.
 173
 174 * Make sure you have GNU make installed.
 175
 176 * Make sure you have an up-to-date version of help2man installed.
 177
 178 * Make sure your locale is sane, e.g. by exporting LC_ALL=C.
 179
 180 * Update the version number in configure.ac.
 181   See http://www.gnu.org/software/libtool/contribute.html for details of
 182   the numbering scheme (m4 uses the same scheme as libtool).
 183
 184 * Update NEWS, ChangeLog.
 185
 186 * Run ./bootstrap.
 187
 188 * Run ./configure (a VPATH build is not recommended, since several
 189   targets in GNUMakefile and Makefile.maint assume an in-tree build for
 190   distribution purposes.  Normal builds do not suffer from this
 191   restriction, and make distcheck ensures VPATH still works).
 192
 193 * Run `make'.  The file doc/m4.1 needs to exist for a distribution, and
 194   be up-to-date with m4 --help output, but `make dist' intentionally
 195   does not depend on running a built binary.
 196
 197 * Run `make distcheck'.  If there are any problems, fix them and start
 198   again.
 199
 200 * Run ./commit from the source tree.
 201
 202 * Run `make cvs-dist', which will build a release tarball (with `make
 203   distcheck') and tag the tree with release-$(VERSION).
 204
 205 * Run `make deltas' (pass LASTRELEASE=maj.min[.mic[alpha]] if needed) to
 206   create both diff and xdelta files between the previous release tarball
 207   and the new.
 208
 209 * Run './gnupload --to [dest].gnu.org:m4 [files]' to create
 210   detached gpg signature and clear signed directive files, and upload
 211   the combination to the correct location.  For an alpha release,
 212   gnupload will place files in alpha.gnu.org, in /incoming/alpha, and
 213   the xdelta file is not strictly necessary.  For a full release,
 214   gnupload will place files in ftp.gnu.org, in /incoming/ftp.
 215
 216 * Send announcement to m4-discuss@gnu.org, m4-announce@gnu.org, and
 217   autotools-announce@gnu.org.  If not an alpha send to info-gnu@gnu.org
 218   as well.  Use the templates below as a starting point.  Contact a list
 219   administrator for m4-announce in advance to ensure your post will
 220   make it through (the list is normally set to silently discard all
 221   posts, even from subscribers).
 222
 223 * Update version number in configure.ac to next alpha number.
 224   See http://www.gnu.org/software/libtool/contribute.html for details of
 225   the numbering scheme.
 226
 227 * Update NEWS, ChangeLog.
 228
 229 * Run ./commit.
 230
 231 * For non-alpha releases, update the webpages.  Replace manual.html with
 232   the new one (generate with `make web-manual').
 233
 234
 235 7. Alpha release note template
 236 ==============================
 237
 238 To: m4-announce@gnu.org, m4-discuss@gnu.org, autotools-announce@gnu.org
 239 Subject: GNU M4 @VERSION@ released (alpha release).
 240
 241 The GNU M4 Team is pleased to announce alpha release @VERSION@ of GNU
 242 M4.
 243
 244 GNU `m4' is an implementation of the traditional Unix macro processor.
 245 It is mostly SVR4 compatible, although it has some extensions (for
 246 example, handling more than 9 positional parameters to macros).  `m4'
 247 also has built-in functions for including files, running shell commands,
 248 doing arithmetic, etc.  Autoconf needs GNU `m4' for generating
 249 `configure' scripts, but not for running them.
 250
 251 Here are the compressed sources:
 252
 253   ftp://alpha.gnu.org/gnu/m4/m4-@VERSION@.tar.gz    [@SIZE@]
 254   ftp://alpha.gnu.org/gnu/m4/m4-@VERSION@.tar.bz2   [@SIZE@]
 255
 256 Here are the xdeltas and diffs against m4-@PREV_RELEASE_VERSION_ON_THIS_BRANCH@:
 257
 258   ftp://alpha.gnu.org/gnu/m4/m4-@PREV_RELEASE_VERSION_ON_THIS_BRANCH@-@VERSION@.diff.gz   [@SIZE@]
 259   ftp://alpha.gnu.org/gnu/m4/m4-@PREV_RELEASE_VERSION_ON_THIS_BRANCH@-@VERSION@.xdelta    [@SIZE@]
 260
 261 Here are the gpg detached signatures:
 262
 263   ftp://alpha.gnu.org/gnu/m4/m4-@VERSION@.tar.gz.sig
 264   ftp://alpha.gnu.org/gnu/m4/m4-@VERSION@.tar.bz2.sig
 265   ftp://alpha.gnu.org/gnu/m4/m4-@PREV_RELEASE_VERSION_ON_THIS_BRANCH@-@VERSION@.diff.gz.sig
 266   ftp://alpha.gnu.org/gnu/m4/m4-@PREV_RELEASE_VERSION_ON_THIS_BRANCH@-@VERSION@.xdelta.sig
 267
 268 You should download the signature named after any tarball you download,
 269 and then verify its integrity with, for example:
 270
 271   gpg --verify m4-@VERSION@.tar.gz.sig
 272
 273 If that command fails because you don't have the required public key,
 274 then run this command to import it:
 275
 276   gpg --keyserver wwwkeys.pgp.net --recv-keys @KEY@
 277
 278 Here are the MD5 and SHA1 checksums:
 279
 280   @MD5SUM@ m4-@VERSION@.tar.gz
 281   @MD5SUM@ m4-@VERSION@.tar.bz2
 282   @MD5SUM@ m4-@PREV_RELEASE_VERSION_ON_THIS_BRANCH@-@VERSION@.diff.gz
 283   @MD5SUM@ m4-@PREV_RELEASE_VERSION_ON_THIS_BRANCH@-@VERSION@.xdelta
 284   @SHA1SUM@ m4-@VERSION@.tar.gz
 285   @SHA1SUM@ m4-@VERSION@.tar.bz2
 286   @SHA1SUM@ m4-@PREV_RELEASE_VERSION_ON_THIS_BRANCH@-@VERSION@.diff.gz
 287   @SHA1SUM@ m4-@PREV_RELEASE_VERSION_ON_THIS_BRANCH@-@VERSION@.xdelta
 288
 289 This release has @SUMMARY_OF_IMPROVEMENTS_SINCE_LAST_RELEASE_ON_THIS_BRANCH@.
 290
 291 This release was bootstrapped with @BOOTSTRAP_TOOLS_WITH_VERSIONS@.
 292
 293 Alternatively, you can fetch the unbootstrapped sourcecode from
 294 anonymous cvs by using the following commands:
 295
 296   $ export CVS_RSH=ssh
 297   $ cvs -z3 -d :pserver:anonymous@cvs.sv.gnu.org:/sources/m4 \
 298   co -r @CVS_RELEASE_TAG@ m4
 299
 300 You will then need to have recent versions of Automake and Autoconf
 301 installed, and a recent checkout of gnulib, in order to bootstrap the
 302 checked out sources yourself.
 303
 304 New in @VERSION@: @RELEASE_DATE@
 305
 306   @EXCERPT_FROM_NEWS_FILE@
 307
 308 Please report bugs to <bug-m4@gnu.org>, along with the output of 'make
 309 check' and any other information that might be useful in resolving the
 310 issue.
 311
 312
 313 8. Full release note template
 314 =============================
 315
 316 To: info-gnu@gnu.org
 317 To: m4-announce@gnu.org, m4-discuss@gnu.org, autotools-announce@gnu.org
 318 Subject: GNU M4 @VERSION@ released.
 319
 320 The GNU M4 Team is pleased to announce the release of GNU M4 @VERSION@.
 321
 322 GNU `m4' is an implementation of the traditional Unix macro processor.
 323 It is mostly SVR4 compatible, although it has some extensions (for
 324 example, handling more than 9 positional parameters to macros).  `m4'
 325 also has built-in functions for including files, running shell commands,
 326 doing arithmetic, etc.  Autoconf needs GNU `m4' for generating
 327 `configure' scripts, but not for running them.
 328
 329 This release has @SUMMARY_OF_IMPROVEMENTS_SINCE_LAST_RELEASE_ON_THIS_BRANCH@.
 330
 331 New in @VERSION@: @RELEASE_DATE@
 332
 333   @EXCERPT_FROM_NEWS_FILE@
 334
 335 m4-@VERSION@ is available now from ftp.gnu.org, along with diffs and
 336 xdeltas against m4-@PREV_RELEASE_VERSION_ON_THIS_BRANCH@ that are also
 337 available from ftp.gnu.org.  Please use a mirror to reduce stress on the
 338 main gnu machine:
 339
 340   http://www.gnu.org/order/ftp.html
 341
 342 Here are the compressed sources:
 343
 344   ftp://ftp.gnu.org/gnu/m4/m4-@VERSION@.tar.gz    [@SIZE@]
 345   ftp://ftp.gnu.org/gnu/m4/m4-@VERSION@.tar.bz2   [@SIZE@]
 346
 347 Here are the xdeltas and diffs against m4-@PREV_RELEASE_VERSION_ON_THIS_BRANCH@:
 348
 349   ftp://ftp.gnu.org/gnu/m4/m4-@PREV_RELEASE_VERSION_ON_THIS_BRANCH@-@VERSION@.diff.gz   [@SIZE@]
 350   ftp://ftp.gnu.org/gnu/m4/m4-@PREV_RELEASE_VERSION_ON_THIS_BRANCH@-@VERSION@.xdelta    [@SIZE@]
 351
 352 Here are the gpg detached signatures:
 353
 354   ftp://ftp.gnu.org/gnu/m4/m4-@VERSION@.tar.gz.sig
 355   ftp://ftp.gnu.org/gnu/m4/m4-@VERSION@.tar.bz2.sig
 356   ftp://ftp.gnu.org/gnu/m4/m4-@PREV_RELEASE_VERSION_ON_THIS_BRANCH@-@VERSION@.diff.gz.sig
 357   ftp://ftp.gnu.org/gnu/m4/m4-@PREV_RELEASE_VERSION_ON_THIS_BRANCH@-@VERSION@.xdelta.sig
 358
 359 You should download the signature named after any tarball you download,
 360 and then verify its integrity with, for example:
 361
 362   gpg --verify m4-@VERSION@.tar.gz.sig
 363
 364 If that command fails because you don't have the required public key,
 365 then run this command to import it:
 366
 367   gpg --keyserver wwwkeys.pgp.net --recv-keys @KEY@
 368
 369 Here are the MD5 and SHA1 checksums:
 370
 371   @MD5SUM@ m4-@VERSION@.tar.gz
 372   @MD5SUM@ m4-@VERSION@.tar.bz2
 373   @MD5SUM@ m4-@PREV_RELEASE_VERSION_ON_THIS_BRANCH@-@VERSION@.diff.gz
 374   @MD5SUM@ m4-@PREV_RELEASE_VERSION_ON_THIS_BRANCH@-@VERSION@.xdelta
 375   @SHA1SUM@ m4-@VERSION@.tar.gz
 376   @SHA1SUM@ m4-@VERSION@.tar.bz2
 377   @SHA1SUM@ m4-@PREV_RELEASE_VERSION_ON_THIS_BRANCH@-@VERSION@.diff.gz
 378   @SHA1SUM@ m4-@PREV_RELEASE_VERSION_ON_THIS_BRANCH@-@VERSION@.xdelta
 379
 380 This release was bootstrapped with @BOOTSTRAP_TOOLS_WITH_VERSIONS@.
 381
 382 Alternatively, you can fetch the unbootstrapped sourcecode from
 383 anonymous cvs by using the following commands:
 384
 385   $ export CVS_RSH=ssh
 386   $ cvs -z3 -d :pserver:anonymous@cvs.sv.gnu.org:/sources/m4 \
 387   co -r @CVS_RELEASE_TAG@ m4
 388
 389 You will then need to have the latest release versions of Automake
 390 (@AUTOMAKE_VERSION@) and Autoconf (@AUTOCONF_VERSION@) installed to
 391 bootstrap the checked out sources yourself.
 392
 393 Please report bugs to <bug-m4@gnu.org>, along with the output of 'make
 394 check' and any other information that might be useful in resolving the
 395 issue.
 396
 397
 398 --
 399 Copyright (C) 2004, 2005, 2006, 2007 Free Software Foundation, Inc.
 400
 401 The canonical source of this file is maintained with the
 402 GNU M4 package.  Report bugs to bug-m4@gnu.org.
 403
 404 GNU M4 is free software: you can redistribute it and/or modify
 405 it under the terms of the GNU General Public License as published by
 406 the Free Software Foundation, either version 3 of the License, or
 407 (at your option) any later version.
 408
 409 GNU M4 is distributed in the hope that it will be useful,
 410 but WITHOUT ANY WARRANTY; without even the implied warranty of
 411 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
 412 GNU General Public License for more details.
 413
 414 You should have received a copy of the GNU General Public License
 415 along with this program.  If not, see <http://www.gnu.org/licenses/>.
 416
 417 Local Variables:
 418 mode: text
 419 fill-column: 72
 420 End:
 421 vim:tw=72