7 This file attempts to describe the processes we use to maintain M4,
8 and is not part of a release distribution.
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.
20 * If somebody reports a new bug, write a test case, then mention his
21 name in the ChangeLog entry.
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.
27 * Changes with user-visible effects must be mentioned in NEWS.
29 * New macros must be blind, or else prefixed with `m4' or `__', in
30 order to minimize backward compatibility issues with previous
31 releases of M4 when processing English text.
33 * GNU Coding Standards should be followed:
34 http://www.gnu.org/prep/standards/
35 Additionally, while GNU M4 is not yet POSIX compliant, we are trying
36 to get closer to it (although some design decisions state that POSIX
37 compliance should only happen when POSIXLY_CORRECT is in the
38 environment or the -G option was passed on the command line):
39 http://www.opengroup.org/onlinepubs/009695399/utilities/m4.html
45 * Before you can build from CVS, you need to bootstrap. This requires a
46 pre-installed version of GNU M4 1.4.5 or later, built from a package;
47 Autoconf 2.60 or later; Automake 1.10a or later; CVS Head of Libtool
48 (will become Libtool 2.0); Gettext 0.16 or later; and a CVS checkout
49 of gnulib. Gnulib can be obtained by:
50 cvs -z3 -d:pserver:anonymous@cvs.sv.gnu.org:/sources/gnulib co gnulib
52 * Either add the gnulib directory to your PATH, or run
53 GNULIB_TOOL=path/to/gnulib/gnulib-tool ./bootstrap
55 * When it is time for a release, it is a good idea to bootstrap with
56 official releases of the autotools, rather than CVS builds, to reduce
57 the pain of a user re-running bootstrap on the packaged M4. However,
58 files installed by Automake should be updated to the latest version
59 from their respective upstream source, rather than the version that
60 shipped with the automake release.
68 liberally, on as many platforms as you can. Use as many compilers and
71 * Some of the testsuite is generated from the documentation.
72 All instances of @example in doc/m4.texinfo that are not preceeded by
73 "@comment ignore" are turned into tests in the tests directory.
76 5. Editing 'ChangeLog'
77 ======================
79 * When in doubt, check that emacs can syntax-color properly in
80 change-log-mode. And preferably use emacs 'C-x 4 a'
81 (add-change-log-entry-other-window) to open ChangeLog with an
82 appropriate new template.
84 * If this change is by a different author, or on a different date to the
85 last entry start a new entry at the top of the file with the format
86 (note two spaces between each field):
88 yyyy-mm-dd Name of Author <email@address>
90 * If more than one person collaborated on the change, additional
91 authors can be listed on subsequent lines, thus:
93 yyyy-mm-dd Name of Main Author <email@address>,
94 Name of Contributor <another@email.address>
96 * Where a change author did not supply a copyright assignment, but the
97 changes they submitted were sufficiently trivial to commit in any case
98 (see the GCS for guidelines on this), then flag this against their
99 name in the header, thus:
101 yyyy-mm-dd Name of Author <email@address> (tiny change)
103 * Preferably the next part should be a description of the overall
104 purpose of the change, separated from the header by a blank line,
105 indented by 1 tab, and filled at column 72. The last character of the
106 description should be a colon, :.
108 * Changes to each file come next. Each new file starts on a new line,
109 indented by 1 tab and starting with an asterisk and a space. Multiple
110 files can be listed here relative to $top_srcdir, and comma separated.
111 Names of functions (or sections as appropriate) to which the change
112 applies should be named inside parentheses and comma separated. If
113 this goes beyond column 72, then parens should be closed and re-opened
116 * file, another/file, test/testcases/foo.test (func_foo)
117 (func_bar, func_baz): Description of changes.
119 * If the change does not apply to particular functions (or sections),
120 the section list can be omitted:
122 * file, another/file, test/testcases/foo.test: General changes.
124 * If the changes are particular to certain architectures, they should be
125 listed after the functions in square brackets:
127 * file, another/file (func_foo) [linux, solaris]: Description of
130 * Subsequent changes in other files that are related to the same overall
131 enhancement or bugfix should be listed concurrently, without blank
132 lines. Always start a fresh line for a new file:
134 * file, another/file (func_foo) [linux, solaris]: Description of
136 * doc/foo.texi (Invoking Foo): Document.
139 * If the change is in response to a problem reported by someone other
140 than the author, then credit them at the end of the description with:
142 Reported by Reporter Name <email@address>.
144 * See the GNU Coding Standards document for more details on ChangeLog
151 * If you are an m4 maintainer, but have not yet registered your
152 gpg public key and (preferred) email address with the FSF, send an
153 email, preferably GPG-signed, to <ftp-upload@gnu.org> that includes
156 (a) name of package(s) that you are the maintainer for, and your
157 preferred email address.
159 (b) an ASCII armored copy of your GnuPG key, as an attachment.
160 ("gpg --export -a YOUR_KEY_ID > mykey.asc" should give you
163 When you have received acknowledgement of your message, the proper GPG
164 keys will be registered on ftp-upload.gnu.org and only then will you be
165 authorized to upload files to the FSF ftp machines.
167 * If you do not have access to the mailing list administrative interface,
168 approach the list owners for the password. Be sure to check the lists
169 (esp. bug-m4) for outstanding bug reports also in the list of
170 pending moderation requests. This step is not strictly necessary.
172 * Make sure you have wget installed.
174 * Make sure you have a copy of xdelta installed, and a copy of the previous
175 release tarball in the build directory.
177 * Make sure your locale is sane, e.g. by exporting LC_ALL=C.
179 * Update the version number in configure.ac.
180 See http://www.gnu.org/software/libtool/contribute.html for details of
181 the numbering scheme (m4 uses the same scheme as libtool).
183 * Update NEWS, ChangeLog.
187 * Run ./configure (or create a build directory first and run configure
188 from there, if you want to keep the build tree separate).
190 * Run `make distcheck'. If there are any problems, fix them and start
193 * Run ./commit from the source tree.
195 * Run `make cvs-dist', which will build a release tarball (with `make
196 distcheck'), and tag the tree with release-$(VERSION).
198 * Run 'make deltas' (pass LASTRELEASE=maj.min[.mic[alpha]] if needed) to
199 create both diff and xdelta files between the previous release tarball
202 * Run '[../]./gnupload --to [dest].gnu.org:m4 [files]' to create
203 detached gpg signature and clear signed directive files, and upload
204 the combination to the correct location. For an alpha release,
205 gnupload will place files in alpha.gnu.org, in /incoming/alpha, and
206 the xdelta file is not strictly necessary. For a full release,
207 gnupload will place files in ftp.gnu.org, in /incoming/ftp.
209 * Send announcement to m4-discuss@gnu.org, m4-announce@gnu.org, and
210 autotools-announce@gnu.org. If not an alpha send to info-gnu@gnu.org
213 * Update version number in configure.ac to next alpha number.
214 See http://www.gnu.org/software/libtool/contribute.html for details of
215 the numbering scheme.
217 * Update NEWS, ChangeLog.
221 * For non-alpha releases, update the webpages. Replace manual.html with
222 the new one (generate with `make web-manual').
224 * Update the M4 entry in the GNU Software directory, located at
225 http://directory.fsf.org/GNU/gnum4.html. To do this, check out the
227 cvs -z3 -d:pserver:anonymous@cvs.sv.gnu.org:/sources/directory \
228 co directory/gnum4.txt
229 then mail the patch to bug-directory@gnu.org.
232 7. Alpha release note template
233 ==============================
235 To: m4-announce@gnu.org, m4-discuss@gnu.org, autotools-announce@gnu.org
236 Subject: GNU M4 @VERSION@ released (alpha release).
238 The GNU M4 Team is pleased to announce alpha release @VERSION@ of GNU
241 GNU `m4' is an implementation of the traditional Unix macro processor.
242 It is mostly SVR4 compatible, although it has some extensions (for
243 example, handling more than 9 positional parameters to macros). `m4'
244 also has built-in functions for including files, running shell commands,
245 doing arithmetic, etc. Autoconf needs GNU `m4' for generating
246 `configure' scripts, but not for running them.
248 Here are the compressed sources:
250 ftp://alpha.gnu.org/gnu/m4/m4-@VERSION@.tar.gz [@SIZE@]
251 ftp://alpha.gnu.org/gnu/m4/m4-@VERSION@.tar.bz2 [@SIZE@]
253 Here are the xdeltas and diffs against m4-@PREV_RELEASE_VERSION_ON_THIS_BRANCH@:
255 ftp://alpha.gnu.org/gnu/m4/m4-@PREV_RELEASE_VERSION_ON_THIS_BRANCH@-@VERSION@.diff.gz [@SIZE@]
256 ftp://alpha.gnu.org/gnu/m4/m4-@PREV_RELEASE_VERSION_ON_THIS_BRANCH@-@VERSION@.xdelta [@SIZE@]
258 Here are the gpg detached signatures:
260 ftp://alpha.gnu.org/gnu/m4/m4-@VERSION@.tar.gz.sig
261 ftp://alpha.gnu.org/gnu/m4/m4-@VERSION@.tar.bz2.sig
262 ftp://alpha.gnu.org/gnu/m4/m4-@PREV_RELEASE_VERSION_ON_THIS_BRANCH@-@VERSION@.diff.gz.sig
263 ftp://alpha.gnu.org/gnu/m4/m4-@PREV_RELEASE_VERSION_ON_THIS_BRANCH@-@VERSION@.xdelta.sig
265 You should download the signature named after any tarball you download,
266 and then verify its integrity with, for example:
268 gpg --verify m4-@VERSION@.tar.gz.sig
270 If that command fails because you don't have the required public key,
271 then run this command to import it:
273 gpg --keyserver wwwkeys.pgp.net --recv-keys @KEY@
275 Here are the MD5 and SHA1 checksums:
277 @MD5SUM@ m4-@VERSION@.tar.gz
278 @MD5SUM@ m4-@VERSION@.tar.bz2
279 @MD5SUM@ m4-@PREV_RELEASE_VERSION_ON_THIS_BRANCH@-@VERSION@.diff.gz
280 @MD5SUM@ m4-@PREV_RELEASE_VERSION_ON_THIS_BRANCH@-@VERSION@.xdelta
281 @SHA1SUM@ m4-@VERSION@.tar.gz
282 @SHA1SUM@ m4-@VERSION@.tar.bz2
283 @SHA1SUM@ m4-@PREV_RELEASE_VERSION_ON_THIS_BRANCH@-@VERSION@.diff.gz
284 @SHA1SUM@ m4-@PREV_RELEASE_VERSION_ON_THIS_BRANCH@-@VERSION@.xdelta
286 This release has @SUMMARY_OF_IMPROVEMENTS_SINCE_LAST_RELEASE_ON_THIS_BRANCH@.
288 This release was bootstrapped with @BOOTSTRAP_TOOLS_WITH_VERSIONS@.
290 Alternatively, you can fetch the unbootstrapped sourcecode from
291 anonymous cvs by using the following commands:
294 $ cvs -z3 -d :pserver:anonymous@cvs.sv.gnu.org:/sources/m4 \
295 co -r @CVS_RELEASE_TAG@ m4
297 You will then need to have recent versions of Automake and Autoconf
298 installed, and a recent checkout of gnulib, in order to bootstrap the
299 checked out sources yourself.
301 New in @VERSION@: @RELEASE_DATE@
303 @EXCERPT_FROM_NEWS_FILE@
305 Please report bugs to <bug-m4@gnu.org>, along with the output of 'make
306 check' and any other information that might be useful in resolving the
310 8. Full release note template
311 =============================
314 To: m4-announce@gnu.org, m4-discuss@gnu.org, autotools-announce@gnu.org
315 Subject: GNU M4 @VERSION@ released.
317 The GNU M4 Team is pleased to announce the release of GNU M4 @VERSION@.
319 GNU `m4' is an implementation of the traditional Unix macro processor.
320 It is mostly SVR4 compatible, although it has some extensions (for
321 example, handling more than 9 positional parameters to macros). `m4'
322 also has built-in functions for including files, running shell commands,
323 doing arithmetic, etc. Autoconf needs GNU `m4' for generating
324 `configure' scripts, but not for running them.
326 This release has @SUMMARY_OF_IMPROVEMENTS_SINCE_LAST_RELEASE_ON_THIS_BRANCH@.
328 New in @VERSION@: @RELEASE_DATE@
330 @EXCERPT_FROM_NEWS_FILE@
332 m4-@VERSION@ is available now from ftp.gnu.org, along with diffs and
333 xdeltas against m4-@PREV_RELEASE_VERSION_ON_THIS_BRANCH@ that are also
334 available from ftp.gnu.org. Please use a mirror to reduce stress on the
337 http://www.gnu.org/order/ftp.html
339 Here are the compressed sources:
341 ftp://ftp.gnu.org/gnu/m4/m4-@VERSION@.tar.gz [@SIZE@]
342 ftp://ftp.gnu.org/gnu/m4/m4-@VERSION@.tar.bz2 [@SIZE@]
344 Here are the xdeltas and diffs against m4-@PREV_RELEASE_VERSION_ON_THIS_BRANCH@:
346 ftp://ftp.gnu.org/gnu/m4/m4-@PREV_RELEASE_VERSION_ON_THIS_BRANCH@-@VERSION@.diff.gz [@SIZE@]
347 ftp://ftp.gnu.org/gnu/m4/m4-@PREV_RELEASE_VERSION_ON_THIS_BRANCH@-@VERSION@.xdelta [@SIZE@]
349 Here are the gpg detached signatures:
351 ftp://ftp.gnu.org/gnu/m4/m4-@VERSION@.tar.gz.sig
352 ftp://ftp.gnu.org/gnu/m4/m4-@VERSION@.tar.bz2.sig
353 ftp://ftp.gnu.org/gnu/m4/m4-@PREV_RELEASE_VERSION_ON_THIS_BRANCH@-@VERSION@.diff.gz.sig
354 ftp://ftp.gnu.org/gnu/m4/m4-@PREV_RELEASE_VERSION_ON_THIS_BRANCH@-@VERSION@.xdelta.sig
356 You should download the signature named after any tarball you download,
357 and then verify its integrity with, for example:
359 gpg --verify m4-@VERSION@.tar.gz.sig
361 If that command fails because you don't have the required public key,
362 then run this command to import it:
364 gpg --keyserver wwwkeys.pgp.net --recv-keys @KEY@
366 Here are the MD5 and SHA1 checksums:
368 @MD5SUM@ m4-@VERSION@.tar.gz
369 @MD5SUM@ m4-@VERSION@.tar.bz2
370 @MD5SUM@ m4-@PREV_RELEASE_VERSION_ON_THIS_BRANCH@-@VERSION@.diff.gz
371 @MD5SUM@ m4-@PREV_RELEASE_VERSION_ON_THIS_BRANCH@-@VERSION@.xdelta
372 @SHA1SUM@ m4-@VERSION@.tar.gz
373 @SHA1SUM@ m4-@VERSION@.tar.bz2
374 @SHA1SUM@ m4-@PREV_RELEASE_VERSION_ON_THIS_BRANCH@-@VERSION@.diff.gz
375 @SHA1SUM@ m4-@PREV_RELEASE_VERSION_ON_THIS_BRANCH@-@VERSION@.xdelta
377 This release was bootstrapped with @BOOTSTRAP_TOOLS_WITH_VERSIONS@.
379 Alternatively, you can fetch the unbootstrapped sourcecode from
380 anonymous cvs by using the following commands:
383 $ cvs -z3 -d :pserver:anonymous@cvs.sv.gnu.org:/sources/m4 \
384 co -r @CVS_RELEASE_TAG@ m4
386 You will then need to have the latest release versions of Automake
387 (@AUTOMAKE_VERSION@) and Autoconf (@AUTOCONF_VERSION@) installed to
388 bootstrap the checked out sources yourself.
390 Please report bugs to <bug-m4@gnu.org>, along with the output of 'make
391 check' and any other information that might be useful in resolving the
396 Copyright (C) 2004, 2005, 2006 Free Software Foundation, Inc.
398 The canonical source of this file is maintained with the
399 GNU M4 package. Report bugs to bug-m4@gnu.org.
401 GNU M4 is free software; you can redistribute it and/or
402 modify it under the terms of the GNU General Public License as
403 published by the Free Software Foundation; either version 2
404 of the License, or (at your option) any later version.
406 GNU M4 is distributed in the hope that it will be useful,
407 but WITHOUT ANY WARRANTY; without even the implied warranty of
408 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
409 General Public License for more details.
411 You should have received a copy of the GNU General Public License
412 along with GNU M4; if not, write to the Free Software
413 Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA