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