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