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.11 or later)
67 - Autoconf 2.62 or later
68 - Automake 1.10a or later
69 - Libtool 2.2 or later
70 - Gettext 0.16 or later
72 - Help2man 1.29 or later
73 - LZMA Utils 4.32 or later (from <http://tukaani.org/lzma/>)
74 - Texinfo 4.8 or later
75 - Any prerequisites of the above (such as perl, tex)
76 - A git checkout of gnulib. A read-only copy of gnulib can be
78 git clone git://git.sv.gnu.org/gnulib.git
80 cvs -d:pserver:anonymous@pserver.git.sv.gnu.org:/srv/git/gnulib.git \
83 If you are a member of the savannah group for gnulib, a read-write
84 copy can be obtained by:
85 git clone <savannah-user>@git.sv.gnu.org:/srv/git/gnulib.git
87 Note that none of these bootstrapping dependencies should be required
88 by a distributed release.
90 * Either add the gnulib directory to your PATH, or run
91 GNULIB_TOOL=path/to/gnulib/gnulib-tool ./bootstrap
93 * When it is time for a release, it is a good idea to bootstrap with
94 official releases of the autotools, rather than git builds, to reduce
95 the pain of a user re-running bootstrap on the packaged M4. However,
96 files installed by Automake should be updated to the latest version
97 from their respective upstream source, rather than the version that
98 shipped with the automake release.
106 liberally, on as many platforms as you can. Use as many compilers and
109 * Some of the testsuite is generated from the documentation.
110 All instances of @example in doc/m4.texinfo that are not preceeded by
111 "@comment ignore" are turned into tests in the tests directory.
114 5. Editing 'ChangeLog'
115 ======================
117 * When in doubt, check that emacs can syntax-color properly in
118 change-log-mode. And preferably use emacs 'C-x 4 a'
119 (add-change-log-entry-other-window) to open ChangeLog with an
120 appropriate new template.
122 * If this change is by a different author, or on a different date to the
123 last entry start a new entry at the top of the file with the format
124 (note two spaces between each field):
126 yyyy-mm-dd Name of Author <email@address>
128 * If more than one person collaborated on the change, additional
129 authors can be listed on subsequent lines, thus:
131 yyyy-mm-dd Name of Main Author <email@address>,
132 Name of Contributor <another@email.address>
134 * Where a change author did not supply a copyright assignment, but the
135 changes they submitted were sufficiently trivial to commit in any case
136 (see the GCS for guidelines on this), then flag this against their
137 name in the header, thus:
139 yyyy-mm-dd Name of Author <email@address> (tiny change)
141 * Preferably the next part should be a description of the overall
142 purpose of the change, separated from the header by a blank line,
143 indented by 1 tab, and filled at column 72. The last character of the
144 description should be a colon, :.
146 * Changes to each file come next. Each new file starts on a new line,
147 indented by 1 tab and starting with an asterisk and a space. Multiple
148 files can be listed here relative to $top_srcdir, and comma separated.
149 Names of functions (or sections as appropriate) to which the change
150 applies should be named inside parentheses and comma separated. If
151 this goes beyond column 72, then parens should be closed and re-opened
154 * file, another/file, test/testcases/foo.test (func_foo)
155 (func_bar, func_baz): Description of changes.
157 * If the change does not apply to particular functions (or sections),
158 the section list can be omitted:
160 * file, another/file, test/testcases/foo.test: General changes.
162 * If the changes are particular to certain architectures, they should be
163 listed after the functions in square brackets:
165 * file, another/file (func_foo) [linux, solaris]: Description of
168 * Subsequent changes in other files that are related to the same overall
169 enhancement or bugfix should be listed concurrently, without blank
170 lines. Always start a fresh line for a new file:
172 * file, another/file (func_foo) [linux, solaris]: Description of
174 * doc/foo.texi (Invoking Foo): Document.
177 * If the change is in response to a problem reported by someone other
178 than the author, then credit them at the end of the description with:
180 Reported by Reporter Name <email@address>.
182 * See the GNU Coding Standards document for more details on ChangeLog
189 * If you are an m4 maintainer, but have not yet registered your
190 gpg public key and (preferred) email address with the FSF, send an
191 email, preferably GPG-signed, to <ftp-upload@gnu.org> that includes
194 (a) name of package(s) that you are the maintainer for, and your
195 preferred email address.
197 (b) an ASCII armored copy of your GnuPG key, as an attachment.
198 ("gpg --export -a YOUR_KEY_ID > mykey.asc" should give you
201 When you have received acknowledgement of your message, the proper GPG
202 keys will be registered on ftp-upload.gnu.org and only then will you be
203 authorized to upload files to the FSF ftp machines.
205 * If you do not have access to the mailing list administrative interface,
206 approach the list owners for the password. Be sure to check the lists
207 (esp. bug-m4) for outstanding bug reports also in the list of
208 pending moderation requests. This step is not strictly necessary.
210 * Make sure you have rsync installed.
212 * Make sure you have a copy of the previous release tarball in the build
215 * Make sure your locale is sane, e.g. by exporting LC_ALL=C.
217 * Update the version number in configure.ac.
218 See http://www.gnu.org/software/libtool/contribute.html for details of
219 the numbering scheme (m4 uses the same scheme as libtool).
221 * Update NEWS, ChangeLog.
225 * Run ./configure (or create a build directory first and run configure
226 from there, if you want to keep the build tree separate).
228 * Run `make distcheck'. If there are any problems, fix them and start
231 * Run ./commit from the source tree.
233 * TODO - adjust this step to account for git:
234 Run `make cvs-dist', which will build a release tarball (with `make
235 distcheck') and tag the tree with release-$(VERSION).
237 * Run 'make deltas' (pass LASTRELEASE=maj.min[.mic[alpha]] if needed) to
238 create diff files between the previous release tarball and the new.
240 * Run '[../]./gnupload --to [dest].gnu.org:m4 [files]' to create
241 detached gpg signature and clear signed directive files, and upload
242 the combination to the correct location. For an alpha release,
243 gnupload will place files in alpha.gnu.org, in /incoming/alpha; for a
244 full release, gnupload will place files in ftp.gnu.org, in
245 /incoming/ftp. Verify that the files uploaded successfully before
246 sending an announcement.
248 * Send announcement to m4-discuss@gnu.org, m4-announce@gnu.org, and
249 autotools-announce@gnu.org. If not an alpha send to info-gnu@gnu.org
250 as well. Use gnulib/build-aux/announce-gen to form an initial
251 template for the announcement (you may also need to install the perl
252 module Digest::SHA1). Contact a list administrator for m4-announce in
253 advance to ensure your post will make it through (the list is normally
254 set to silently discard all posts, even from subscribers).
256 * Update version number in configure.ac to next alpha number.
257 See http://www.gnu.org/software/libtool/contribute.html for details of
258 the numbering scheme.
260 * Update NEWS, ChangeLog.
264 * For non-alpha releases, update the webpages. Replace manual.html with
265 the new one (generate with `make web-manual').
267 * Update the Free Software Directory. Browse to:
268 http://directory.fsf.org/project/m4/
269 and send an email to <bug-directory@gnu.org> mentioning any
270 content that needs to be updated.
273 Copyright (C) 2004, 2005, 2006, 2007, 2008, 2009 Free Software
276 The canonical source of this file is maintained with the
277 GNU M4 package. Report bugs to bug-m4@gnu.org.
279 GNU M4 is free software: you can redistribute it and/or modify
280 it under the terms of the GNU General Public License as published by
281 the Free Software Foundation, either version 3 of the License, or
282 (at your option) any later version.
284 GNU M4 is distributed in the hope that it will be useful,
285 but WITHOUT ANY WARRANTY; without even the implied warranty of
286 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
287 GNU General Public License for more details.
289 You should have received a copy of the GNU General Public License
290 along with this program. If not, see <http://www.gnu.org/licenses/>.