summaryrefslogtreecommitdiff
path: root/HACKING
blob: eb335963d3279db6d2477f2b71ce5a1abb2f71cb (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
GNU M4
******

1. Introduction
===============

This file attempts to describe the processes we use to maintain M4,
and is not part of a release distribution.


2. Maintenance Notes
====================

* If you incorporate a change from somebody on the net:
  If it is a large change, you must make sure they have signed the
  appropriate paperwork, and be sure to add their name and email
  address to THANKS.  AUTHORS is built from the FSF list of copyright
  assignments, on fencepost.gnu.org.

* If somebody reports a new bug, write a test case, then mention his
  name in the ChangeLog entry.

* The correct response to most actual bugs is to write a new test case
  which demonstrates the bug.  Then fix the bug, re-run the test suite,
  and check everything in.

* Changes with user-visible effects must be mentioned in NEWS.

* GNU Coding Standards should be followed:
    https://www.gnu.org/prep/standards/
  Additionally, while GNU M4 is not yet POSIX compliant, we are trying
  to get closer to it (although some design decisions state that POSIX
  compliance should only happen when POSIXLY_CORRECT is in the
  environment or the -G option was passed on the command line):
    https://www.opengroup.org/onlinepubs/009695399/utilities/m4.html


3. Bootstrapping
================

* The master M4 repository is stored in git.

* Before you can build from git, you need to bootstrap.  This requires:
  - A pre-installed version of GNU M4 1.4 or later, built from a package
  - Autoconf 2.64 or later
  - Automake 1.11.1 or later
  - Gettext 0.19.2 or later
  - Help2man 1.29 or later
  - Xz 4.999.8beta or later (from <http://tukaani.org/xz/>)
  - Texinfo 4.11 or later
  - Any prerequisites of the above (such as perl, tex)

  Note that none of these bootstrapping dependencies should be required
  by a distributed release.

* M4 has an optional build dependency.  In order to ensure that the
  dependency remains optional, you can avoid the library by using
  `./configure --without-libsigsegv-prefix'.  In order to ensure that
  the dependency is still viable with the current code base, you should
  install:
  - Libsigsegv 2.6 or later (2.9 or later recommended)

* M4 includes gnulib as a git submodule.  By default, the bootstrap
  script will attempt to run
    git submodule update --init
  to grab a gnulib clone from the official read-only location of
    https://git.savannah.gnu.org/git/gnulib.git

  However, this can be network and disk intensive.  If you already have
  another gnulib clone on your disk, you can use the environment
  variable GNULIB_SRCDIR to point to the previous checkout to speed up
  the process.  Additionally, both the bootstrap script and gnulib-tool
  require a shell that supports functions, so you can set the
  environment variable CONFIG_SHELL to choose a better shell on systems
  (like Solaris) where /bin/sh is lacking.  Thus, you may find it
  convenient to run:
    GNULIB_SRCDIR=path/to/gnulib CONFIG_SHELL=path/to/sh \
      path/to/sh ./bootstrap

  A read-only copy of gnulib can be obtained by:
      git clone https://git.savannah.gnu.org/git/gnulib.git

  Using a CVS checkout might work, but it is relatively untested,
  particularly now that we use a git submodule for gnulib.

  If you are a member of the savannah group for gnulib, a read-write
  copy can be obtained by:
    git clone <savannah-user>@git.sv.gnu.org:/srv/git/gnulib.git

  If you are behind a firewall that blocks the git protocol, you may
  find it useful to do:
    git config --global url.https://git.savannah.gnu.org/r/.insteadof \
      git://git.sv.gnu.org/
  to force git to transparently rewrite all savannah git references to
  instead use https.

* When it is time for a release, it is a good idea to bootstrap with
  official releases of the autotools, rather than git builds, to reduce
  the pain of a user re-running bootstrap on the packaged M4.  However,
  files installed by Automake should be updated to the latest version
  from their respective upstream source, rather than the version that
  shipped with the automake release.

* If you would like to check that you are not missing out on any useful
  gnulib modules, comment out the gl_ASSERT_NO_GNULIB_POSIXCHECK in
  configure.ac, then run 'make CFLAGS='-DGNULIB_POSIXCHECK=1' with gcc,
  and look at the resulting warnings.


4. Test Suite
=============

* Use
    make check
  liberally, on as many platforms as you can.  Use as many compilers and
  linkers you can.

* For branch-1.4, the testsuite is generated from the documentation.
  All instances of @example in doc/m4.texi that are not preceeded by
  "@comment ignore" are turned into tests in the checks directory.


5. Continuous Integration
=========================

* The package is built automatically, at regular intervals.  You can
  find the latest build results here:
    https://gitlab.com/gnu-m4/ci-distcheck/pipelines
    https://gitlab.com/gnu-m4/ci-distcheck/-/jobs?scope=finished


6. Editing 'ChangeLog'
======================

* The ChangeLog is generated from git commit comments.  Each commit log
  should start with a one-line summary, a blank line, and then a
  ChangeLog-style entry for all affected files.  However, it's fine --
  even recommended -- to write a few lines of prose describing the
  change, when the summary and ChangeLog entries don't give enough of
  the big picture.  Omit the leading TABs that you're used to seeing in
  a "real" ChangeLog file, but keep the maximum line length at 72 or
  smaller, so that the generated ChangeLog lines, each with its leading
  TAB, will not exceed 80 columns.  As for the ChangeLog-style content,
  please follow these guidelines:

    https://www.gnu.org/software/guile/changelogs/guile-changelogs_3.html

* When in doubt, check that emacs can syntax-color properly in
  change-log-mode.  And preferably use emacs 'C-x 4 a'
  (add-change-log-entry-other-window) to open ChangeLog with an
  appropriate new template, which you can then paste into your git
  commit editing session.

* See the GNU Coding Standards document for more details on ChangeLog
  formatting.

7. Formatting
=============

* Use space-only indentation in nearly all files (Makefile inputs being
  the exception).

  If you use Emacs and your m4 working directory name matches,
  this code in your ~/.emacs enables the right mode:

  ;; In m4, indent with spaces everywhere (not TABs).
  ;; Exceptions: Makefile and ChangeLog modes.
  (add-hook 'find-file-hook '(lambda ()
    (if (and buffer-file-name
             (string-match "/m4\\>" (buffer-file-name))
             (not (string-equal mode-name "Change Log"))
             (not (string-equal mode-name "Makefile")))
        (setq indent-tabs-mode nil))))

* Since the source code was massively converted from tabs in December
  2009, you may find it helpful to use 'git diff -w' and 'git blame -w'
  helpful for overlooking the whitespace changes.

* Avoid #ifdefs inside function bodies, whenever possible.  If you
  encounter a portability issue, it is better to propose a gnulib module
  that works around it, and have m4 use that module.


8. Release Procedure
====================

* If you are an m4 maintainer, but have not yet registered your
  gpg public key and (preferred) email address with the FSF, send an
  email, preferably GPG-signed, to <ftp-upload@gnu.org> that includes
  the following:

    (a) name of package(s) that you are the maintainer for, and your
        preferred email address.

    (b) an ASCII armored copy of your GnuPG key, as an attachment.
        ("gpg --export -a YOUR_KEY_ID > mykey.asc" should give you
        this.)

  When you have received acknowledgement of your message, the proper GPG
  keys will be registered on ftp-upload.gnu.org and only then will you be
  authorized to upload files to the FSF ftp machines.

* If you do not have access to the mailing list administrative interface,
  approach the list owners for the password.  Be sure to check the lists
  (esp. bug-m4) for outstanding bug reports also in the list of
  pending moderation requests.  This step is not strictly necessary, but
  helps, since by default, m4-announce rejects all posts, so you have to
  get an administrator to allow your announcement through.

* Make sure you have appropriate up-to-date tools installed, including:
  wget
  GNU make
  help2man
  texi2dvi

* Make sure your locale is sane, e.g. by exporting LC_ALL=C.

* Make sure you are happy with the particular gnulib version recorded as
  the gnulib submodule.  If necessary to update to the latest, run:
    git submodule foreach git pull origin master
    git commit -m 'maint: update gnulib submodule to latest' gnulib

* Run ./bootstrap, perhaps with environment variables set.

* Run ./configure (a VPATH build should work, but is less tested).

* Run `make'.  The file doc/m4.1 needs to exist for a distribution, and
  be up-to-date with m4 --help output, but `make dist' intentionally
  does not depend on running a built binary.

* Make sure README properly describes the current release type (stable,
  alpha, or current).

* Run `git commit' from the source tree if there are any changes from
  the previous steps.

* Run `make release-commit RELEASE="X.Y $type"' (for the correct X.Y and
  release type), to update the version number in NEWS.  See
  https://www.gnu.org/software/libtool/contribute.html for details of the
  numbering scheme (M4 uses a similar scheme to libtool, although
  intra-release versions carry more information thanks to
  git-version-gen).  This tags the potential release, but do not push
  anything upstream at this point.

* Run `make distcheck'.  If there are any problems, fix them, then run
  `git tag -d v<version>; git reset --hard HEAD^' to undo the tag, and
  start again from the `git commit' step.

* Run `make <target>', with target set to `stable', `alpha', or `beta'
  as appropriate.  This will run various additional checks, as well as
  spell out the preferred gnupload commands to use in the next step, and
  create a post-release commit that updates NEWS for subsequent edits.

* Run './build-aux/gnupload --to [dest].gnu.org:m4 --symlink-regex [files]'
  to create detached gpg signature and clear signed directive files, and
  upload the combination to the correct location.  For an alpha release,
  gnupload will place files in alpha.gnu.org, in /incoming/alpha; for a
  full release, gnupload will place files in ftp.gnu.org, in
  /incoming/ftp.

* Send announcement to m4-discuss@gnu.org, m4-announce@gnu.org, and
  autotools-announce@gnu.org.  If not an alpha send to info-gnu@gnu.org
  as well.  Use ~/announce-m4-<version>, created during the above
  `make <target>' run, as a starting point.  Contact a list
  administrator for m4-announce in advance to ensure your post will make
  it through (the list is normally set to silently discard all posts,
  even from subscribers).

* Run `git push origin refs/tags/v<version>' to push the release tag and
  complete the release.

* For non-alpha releases, update the webpages accessible via
    https://www.gnu.org/software/m4/manual/
  by running this:
    build-aux/gnu-web-doc-update --mirror
  You may also need to add a --user=YOUR_SAVANNAH_USERNAME option.

  You may also need to update the main landing page
    https://www.gnu.org/software/m4/
  by running this:
    cvs -d $YOUR_SAVANNAH_USERNAME@cvs.sv.gnu.org:/webcvs/m4 co m4
    # edit m4/m4.html
    cvs -d $YOUR_SAVANNAH_USERNAME@cvs.sv.gnu.org:/webcvs/m4 ci

* Make a News entry on savannah

* Inform the translation project of the release.  Send mail to:
  coordinator@translationproject.org with the subject "m4-VERSION.pot"
  and a link to the tarball download URL in the body.

* Update the Free Software Directory.  Checkout the CVS sources:
    cvs -d :pserver:anonymous@cvs.sv.gnu.org:/sources/directory \
      co directory/m4.txt
  After making edits, mail the diff to <bug-directory@gnu.org>.


Copyright (C) 2004-2014, 2016-2017, 2020-2023 Free Software Foundation,
Inc.

The canonical source of this file is maintained with the
GNU M4 package.  Report bugs to bug-m4@gnu.org.

GNU M4 is free software: you can redistribute it and/or modify
it under the terms of the GNU General Public License as published by
the Free Software Foundation, either version 3 of the License, or
(at your option) any later version.

GNU M4 is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
GNU General Public License for more details.

You should have received a copy of the GNU General Public License
along with this program.  If not, see <https://www.gnu.org/licenses/>.

Local Variables:
mode: text
fill-column: 72
End:
vim:tw=72