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
41 * Except for third-party files (libtool, gnulib, ...), all .c files
42 should #include <config.h> before anything else (since there are some
43 #defines in config.h that potentially impact system headers, such as
44 when the user does ./configure --disable-assert). This means that no
45 .h files need to #include <config.h>. However, users compiling
46 external modules should be able to compile without <config.h>, since
47 <config.h> is specific to the M4 build and is not installable.
53 * The master M4 repository is stored in git. You can obtain a read-only
55 git clone git://git.sv.gnu.org/m4.git
57 cvs -d:pserver:anonymous@pserver.git.sv.gnu.org:/srv/git/m4.git \
60 If you are a member of the savannah group for M4, a read-write
61 copy can be obtained by:
62 git clone <savannah-user>@git.sv.gnu.org:/srv/git/m4.git
64 * Before you can build from git, you need to bootstrap. This requires:
65 - A pre-installed version of GNU M4 1.4.5 or later, built from a
66 package (recommend 1.4.13 or later)
67 - A git checkout of Autoconf (2.63b-41 or later)
68 - Automake 1.10b or later
69 - Libtool 2.2 or later
70 - Gettext 0.16 or later
72 - Help2man 1.29 or later
73 - Xz 4.999.8beta or later (from <http://tukaani.org/xz/>)
74 - Texinfo 4.8 or later
75 - Any prerequisites of the above (such as perl, tex)
77 Note that none of these bootstrapping dependencies should be required
78 by a distributed release.
80 * M4 includes gnulib as a git submodule. By default, the bootstrap
81 script will attempt to run
82 git submodule update --init
83 to grab a gnulib clone from the official read-only location of
84 git://git.sv.gnu.org/gnulib.git
86 However, this can be network and disk intensive. If you already have
87 another gnulib clone on your disk, you can use the environment
88 variable GNULIB_SRCDIR to point to the previous checkout to speed up
89 the process. Additionally, both the bootstrap script and gnulib-tool
90 require a shell that supports functions, so you can set the
91 environment variable CONFIG_SHELL to choose a better shell on systems
92 (like Solaris) where /bin/sh is lacking. Thus, you may find it
94 GNULIB_SRCDIR=path/to/gnulib CONFIG_SHELL=path/to/sh \
95 path/to/sh ./bootstrap
97 A read-only copy of gnulib can be obtained by:
98 git clone git://git.sv.gnu.org/gnulib.git
100 cvs -d:pserver:anonymous@pserver.git.sv.gnu.org:/srv/git/gnulib.git \
103 Using a CVS checkout might work, but it is relatively untested,
104 particularly now that we use a git submodule for gnulib.
106 If you are a member of the savannah group for gnulib, a read-write
107 copy can be obtained by:
108 git clone <savannah-user>@git.sv.gnu.org:/srv/git/gnulib.git
110 If you are behind a firewall that blocks the git protocol, you may
111 find it useful to do:
112 git config --global url.http://git.sv.gnu.org/r/.insteadof \
113 git://git.sv.gnu.org/
114 to force git to transparently rewrite all savannah git references to
117 * Either add the gnulib directory to your PATH, or run
118 GNULIB_TOOL=path/to/gnulib/gnulib-tool ./bootstrap
120 * When it is time for a release, it is a good idea to bootstrap with
121 official releases of the autotools, rather than git builds, to reduce
122 the pain of a user re-running bootstrap on the packaged M4. However,
123 files installed by Automake should be updated to the latest version
124 from their respective upstream source, rather than the version that
125 shipped with the automake release.
133 liberally, on as many platforms as you can. Use as many compilers and
136 * Some of the testsuite is generated from the documentation.
137 All instances of @example in doc/m4.texinfo that are not preceeded by
138 "@comment ignore" are turned into tests in the tests directory.
141 5. Editing 'ChangeLog'
142 ======================
144 * When in doubt, check that emacs can syntax-color properly in
145 change-log-mode. And preferably use emacs 'C-x 4 a'
146 (add-change-log-entry-other-window) to open ChangeLog with an
147 appropriate new template.
149 * If this change is by a different author, or on a different date to the
150 last entry start a new entry at the top of the file with the format
151 (note two spaces between each field):
153 yyyy-mm-dd Name of Author <email@address>
155 * If more than one person collaborated on the change, additional
156 authors can be listed on subsequent lines, thus:
158 yyyy-mm-dd Name of Main Author <email@address>,
159 Name of Contributor <another@email.address>
161 * Where a change author did not supply a copyright assignment, but the
162 changes they submitted were sufficiently trivial to commit in any case
163 (see the GCS for guidelines on this), then flag this against their
164 name in the header, thus:
166 yyyy-mm-dd Name of Author <email@address> (tiny change)
168 * Preferably the next part should be a description of the overall
169 purpose of the change, separated from the header by a blank line,
170 indented by 1 tab, and filled at column 72. The last character of the
171 description should be a colon, :.
173 * Changes to each file come next. Each new file starts on a new line,
174 indented by 1 tab and starting with an asterisk and a space. Multiple
175 files can be listed here relative to $top_srcdir, and comma separated.
176 Names of functions (or sections as appropriate) to which the change
177 applies should be named inside parentheses and comma separated. If
178 this goes beyond column 72, then parens should be closed and re-opened
181 * file, another/file, test/testcases/foo.test (func_foo)
182 (func_bar, func_baz): Description of changes.
184 * If the change does not apply to particular functions (or sections),
185 the section list can be omitted:
187 * file, another/file, test/testcases/foo.test: General changes.
189 * If the changes are particular to certain architectures, they should be
190 listed after the functions in square brackets:
192 * file, another/file (func_foo) [linux, solaris]: Description of
195 * Subsequent changes in other files that are related to the same overall
196 enhancement or bugfix should be listed concurrently, without blank
197 lines. Always start a fresh line for a new file:
199 * file, another/file (func_foo) [linux, solaris]: Description of
201 * doc/foo.texi (Invoking Foo): Document.
204 * If the change is in response to a problem reported by someone other
205 than the author, then credit them at the end of the description with:
207 Reported by Reporter Name <email@address>.
209 * See the GNU Coding Standards document for more details on ChangeLog
216 * If you are an m4 maintainer, but have not yet registered your
217 gpg public key and (preferred) email address with the FSF, send an
218 email, preferably GPG-signed, to <ftp-upload@gnu.org> that includes
221 (a) name of package(s) that you are the maintainer for, and your
222 preferred email address.
224 (b) an ASCII armored copy of your GnuPG key, as an attachment.
225 ("gpg --export -a YOUR_KEY_ID > mykey.asc" should give you
228 When you have received acknowledgement of your message, the proper GPG
229 keys will be registered on ftp-upload.gnu.org and only then will you be
230 authorized to upload files to the FSF ftp machines.
232 * If you do not have access to the mailing list administrative interface,
233 approach the list owners for the password. Be sure to check the lists
234 (esp. bug-m4) for outstanding bug reports also in the list of
235 pending moderation requests. This step is not strictly necessary.
237 * Make sure you have rsync installed.
239 * Make sure you have a copy of the previous release tarball in the build
242 * Make sure your locale is sane, e.g. by exporting LC_ALL=C.
244 * Make sure you are happy with the particular gnulib version recorded as
245 the gnulib submodule. If necessary to update to the latest, run:
246 git submodule foreach git pull origin master
247 git commit -m 'Update gnulib submodule to latest.' gnulib
249 * Update the version number in configure.ac.
250 See http://www.gnu.org/software/libtool/contribute.html for details of
251 the numbering scheme (m4 uses the same scheme as libtool).
253 * Update NEWS, ChangeLog.
255 * Run ./bootstrap, perhaps with environment variables set.
257 * Run ./configure (or create a build directory first and run configure
258 from there, if you want to keep the build tree separate).
260 * Run `make distcheck'. If there are any problems, fix them and start
263 * Run ./commit from the source tree.
265 * TODO - adjust this step to account for git:
266 Run `make cvs-dist', which will build a release tarball (with `make
267 distcheck') and tag the tree with release-$(VERSION).
269 * Run 'make deltas' (pass LASTRELEASE=maj.min[.mic[alpha]] if needed) to
270 create diff files between the previous release tarball and the new.
272 * Run '[../]./gnupload --to [dest].gnu.org:m4 [files]' to create
273 detached gpg signature and clear signed directive files, and upload
274 the combination to the correct location. For an alpha release,
275 gnupload will place files in alpha.gnu.org, in /incoming/alpha; for a
276 full release, gnupload will place files in ftp.gnu.org, in
277 /incoming/ftp. Verify that the files uploaded successfully before
278 sending an announcement.
280 * Send announcement to m4-discuss@gnu.org, m4-announce@gnu.org, and
281 autotools-announce@gnu.org. If not an alpha send to info-gnu@gnu.org
282 as well. Use gnulib/build-aux/announce-gen to form an initial
283 template for the announcement (you may also need to install the perl
284 module Digest::SHA1). Contact a list administrator for m4-announce in
285 advance to ensure your post will make it through (the list is normally
286 set to silently discard all posts, even from subscribers).
288 * Update version number in configure.ac to next alpha number.
289 See http://www.gnu.org/software/libtool/contribute.html for details of
290 the numbering scheme.
292 * Update NEWS, ChangeLog.
296 * For non-alpha releases, update the webpages. Replace manual.html with
297 the new one (generate with `make web-manual').
299 * Update the Free Software Directory. Browse to:
300 http://directory.fsf.org/project/m4/
301 and send an email to <bug-directory@gnu.org> mentioning any
302 content that needs to be updated.
305 Copyright (C) 2004, 2005, 2006, 2007, 2008, 2009 Free Software
308 The canonical source of this file is maintained with the
309 GNU M4 package. Report bugs to bug-m4@gnu.org.
311 GNU M4 is free software: you can redistribute it and/or modify
312 it under the terms of the GNU General Public License as published by
313 the Free Software Foundation, either version 3 of the License, or
314 (at your option) any later version.
316 GNU M4 is distributed in the hope that it will be useful,
317 but WITHOUT ANY WARRANTY; without even the implied warranty of
318 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
319 GNU General Public License for more details.
321 You should have received a copy of the GNU General Public License
322 along with this program. If not, see <http://www.gnu.org/licenses/>.