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