Merge branch 'preproc' into maint
[platform/upstream/automake.git] / HACKING
1 ============================================================================
2 = This file
3
4 * This file attempts to describe the rules to use when hacking
5   automake.
6
7 ============================================================================
8 = Administrivia
9
10 * The correct response to most actual bugs is to write a new test case
11   which demonstrates the bug.  Then fix the bug, re-run the test suite,
12   and check everything in.
13
14 * If you incorporate a change from somebody on the net:
15   First, if it is a large change, you must make sure they have signed the
16   appropriate paperwork.
17   Second, be sure to add their name and email address to THANKS.
18
19 * If a change fixes a test, mention the test in the commit message.
20   If a change fixes a bug registered in the Automake debbugs tracker,
21   mention the bug number in the commit message.
22
23 * If somebody reports a new bug, mention his name in the commit message
24   and in the test case you write.  Put him into THANKS.
25
26 * When documenting a non-trivial idiom or example in the manual, be
27   sure to add a test case for it, and to reference such test case from
28   a proper Texinfo comment.
29
30 * Some files in the automake package are not owned by automake; these
31   files are listed in the $(FETCHFILES) variable in Makefile.am.  They
32   should never be edited here.  Almost all of them can be updated from
33   respective upstreams with "make fetch" (this should be done especially
34   before releases).  The only exception is the 'lib/COPYING' (from FSF),
35   which should be updated by hand whenever the GPL gets updated (which
36   shouldn't happen that often anyway :-)
37
38 * Changes other than bug fixes must be mentioned in NEWS.  Important
39   bug fixes should be mentioned in NEWS, too.
40
41 * Changes which are potentially controversial, require a non-trivial
42   plan, or must be implemented gradually with a roadmap spanning several
43   releases (either minor or major) should be discussed on the list,
44   and have a proper entry in the PLANS directory.  This entry should be
45   always committed in the "maint" branch, even if the change it deals
46   with is only for the master branch, or a topic branch.  Usually, in
47   addition to this, it is useful to open a "wishlist" report on the
48   Automake debbugs tracker, to keep the idea more visible, and have the
49   discussions surrounding it easily archived in a central place.
50
51 ============================================================================
52 = Naming
53
54 * We've adopted the convention that internal AC_SUBSTs should be
55   named with a leading 'am__', and internally generated targets
56   should be named with a leading 'am--'.  This convention, although
57   in place from at least February 2001, isn't yet universally used.
58   But all new code should use it.
59
60   We used to use '_am_' as the prefix for an internal AC_SUBST.
61   However, it turns out that NEWS-OS 4.2R complains if a Makefile
62   variable begins with the underscore character.  Yay for them.
63   I changed the target naming convention just to be safe.
64
65 ============================================================================
66 = Editing '.am' files
67
68 * Always use $(...) and not ${...}
69
70 * Use ':', not 'true'.  Use 'exit 1', not 'false'.
71
72 * Use '##' comments liberally.  Comment anything even remotely
73   unusual.
74
75 * Never use basename or dirname.  Instead use sed.
76
77 * Do not use 'cd' within back-quotes, use '$(am__cd)' instead.
78   Otherwise the directory name may be printed, depending on CDPATH.
79   More generally, do not ever use plain 'cd' together with a relative
80   directory that does not start with a dot, or you might end up in one
81   computed with CDPATH.
82
83 * For install and uninstall rules, if a loop is required, it should be
84   silent.  Then the body of the loop itself should print each
85   "important" command it runs.  The printed commands should be preceded
86   by a single space.
87
88 * Ensure install rules do not create any installation directory where
89   nothing is to be actually installed.  See automake bug#11030.
90
91 ============================================================================
92 = Editing automake.in and aclocal.in
93
94 * Indent using GNU style.  For historical reasons, the perl code
95   contains portions indented using Larry Wall's style (perl-mode's
96   default), and other portions using the GNU style (cperl-mode's
97   default).  Write new code using GNU style.
98
99 * Don't use & for function calls, unless really required.
100   The use of & prevents prototypes from being checked.
101
102 ============================================================================
103 = Automake versioning and compatibility scheme
104
105 * There are three kinds of automake releases:
106
107     - new major releases (e.g., 2.0, 5.0)
108     - new minor releases (e.g., 1.14, 2.1)
109     - micro a.k.a. "bug-fixing" releases (e.g., 1.13.2, 2.0.1, 3.5.17).
110
111   A new major release should have the major version number bumped, and
112   the minor and micro version numbers reset to zero.  A new minor release
113   should have the major version number unchanged, the minor version number
114   bumped, and the micro version number reset to zero.  Finally, a new
115   micro version should have the major and minor version numbers unchanged,
116   and the micro version number bumped.
117
118   For example, the first minor version after 1.13.2 will be 1.14; the
119   first bug-fixing version after 1.14 that will be 1.14.1; the first
120   new major version after all such releases will be 2.0; the first
121   bug-fixing version after 2.0 will be 2.0.1; and a further bug-fixing
122   version after 2.0.1 will be 2.0.2.
123
124 * Micro releases should be just bug-fixing releases; no new features
125   should be added, and ideally, only trivial bugs, recent regressions,
126   or documentation issues should be addressed by them.
127
128 * Minor releases can introduce new "safe" features, do non-trivial
129   but mostly safe code clean-ups, and even add new runtime warnings
130   (rigorously non-fatal); but they shouldn't include any backward
131   incompatible change, nor contain any potentially destabilizing
132   refactoring or sweeping change, nor introduce new features whose
133   implementation might be liable to cause bugs or regressions in
134   existing code.
135
136 * Major releases can introduce backward-incompatibilities (albeit
137   such incompatibilities should be announced well in advance, and
138   a smooth transition plan prepared for them), and try more risking
139   and daring refactorings and code cleanups.
140
141 * For more information, refer to the extensive discussion associated
142   with automake bug#13578.
143
144 ============================================================================
145 = Working with git
146
147 * To regenerate dependent files created by aclocal and automake,
148   use the 'bootstrap.sh' script.  It uses the code from the source
149   tree, so the resulting files (aclocal.m4 and Makefile.in) should
150   be the same as you would get if you install this version of
151   automake and use it to generate those files.  Be sure to have the
152   latest stable version of Autoconf installed and available early
153   in your PATH.
154
155 * The Automake git tree currently carries three basic branches: 'maint',
156   'master' and 'next'.
157
158 * The 'maint' branch, reserved to changes that should go into the next
159   micro release; so it will just see fixes for regressions, trivial
160   bugs, or documentation issues, and no "active" development whatsoever.
161   Since emergency regression-fixing or security releases could be cut
162   from this branch at any time, it should always be kept in a releasable
163   state.
164
165 * The 'master' branch is where the development of the next minor release
166   takes place.  It should be kept in a stable, almost-releasable state,
167   to simplify testing and deploying of new minor version.  Note that
168   this is not a hard rule, and such "stability" is not expected to be
169   absolute (emergency releases are cut from maint anyway).
170
171 * The 'next' branch is reserved for the development of the next major
172   release.  Experimenting a little here is OK, but don't let the branch
173   grow too unstable; if you need to do exploratory programming
174   or over-arching change, you should use a dedicated topic branch, and
175   only merge that back once it is reasonably stable.
176
177 * The 'maint' branch should be kept regularly merged into the 'master'
178   branch, and the 'master' branch into the 'next' branch.  It is advisable
179   to merge only after a set of related commits have been applied, to avoid
180   introducing too much noise in the history.
181
182 * There may be a number of longer-lived feature branches for new
183   developments.  They should be based off of a common ancestor of all
184   active branches to which the feature should or might be merged later.
185
186 * After a new minor release is done, the 'master' branch is to be merged
187   into the 'maint' branch, and then a "new" 'master' branch created
188   stemming from the resulting commit.
189   Similarly, after a new major release is done, the 'next' branch is to
190   be merged into both the 'master' and 'maint' branch, and then "new"
191   'master' and 'next' branches created stemming from the resulting commit.
192
193 * When fixing a bug (especially a long-standing one), it may be useful
194   to commit the fix to a new temporary branch based off the commit that
195   introduced the bug.  Then this "bugfix branch" can be merged into all
196   the active branches descending from the buggy commit.  This offers a
197   simple way to fix the bug consistently and effectively.
198
199 * When merging, prefer 'git merge --log' over plain 'git merge', so that
200   a later 'git log' gives an indication of which actual patches were
201   merged even when they don't appear early in the list.
202
203 * The 'master' and 'maint' branches should not be rewound, i.e., should
204   always fast-forward, except maybe for privacy issues.  For 'next'
205   (if that will ever be implemented), and for feature branches, the
206   announcement for the branch should document rewinding policy.  If a
207   topic branch is expected to be rewound, it is good practice to put
208   it in the 'experimental/*' namespace; for example, a rewindable branch
209   dealing with Vala support could be named like "experimental/vala-work".
210
211 ============================================================================
212 = Writing a good commit message
213
214 * Here is the general format that Automake's commit messages are expected
215   to follow.  See the further points below for clarifications and minor
216   corrections.
217
218       topic: brief description (this is the "summary line")
219
220       <reference to relevant bugs, if any>
221
222       Here goes a more detailed explanation of why the commit is needed,
223       and a general overview of what it does, and how.  This section
224       should almost always be provided, possibly only with the expection
225       of obvious fixes or very trivial changes.
226
227       And if the detailed explanation is quite long or detailed, you can
228       want to break it in more paragraphs.
229
230       Then you can add references to relevant mailing list discussions
231       (if any), with proper links.  But don't take this as an excuse for
232       writing incomplete commit messages!  The "distilled" conclusions
233       reached in such discussions should have been placed in the
234       paragraphs above.
235
236       Finally, here you can thank people that motivated or helped the
237       change.  So, thanks to John Doe for bringing up the issue, and to
238       J. Random Hacker for providing suggestions and testing the patch.
239
240       <detailed list of touched files>
241
242 * The <detailed list of touched files> should usually be provided (but
243   for short or trivial changes), and should follow the GNU guidelines
244   for ChangeLog entries (described explicitly in the GNU Coding
245   Standards); it might be something of this sort:
246
247     * some/file (func1): Improved frobnication.
248     (func2): Adjusted accordingly.
249     * another/file (foo, bar): Likewise.
250     * tests/foo.tap: New test.
251     * tests/Makefile.am (TESTS): Add it.
252
253 * If your commit fixes an automake bug registered in the tracker (say
254   numbered 1234), you should put the following line after the summary
255   line:
256
257       This change fixes automake bug#1234.
258
259 * If your commit is just related to the given bug report, but does not
260   fix it, you might want to add a line like this instead:
261
262       This change is related to automake bug#1234.
263
264 * When referring to older commits, use 'git describe' output as pointer.
265   But also try to identify the given commit by date and/or summary line
266   if possible.  Examples:
267
268       Since yesterday's commit, v1.11-2019-g4d2bf42, ...
269
270       ... removed in commit 'v1.11-1674-g02e9072' of 01-01-2012,
271       "dist: ditch support for lzma"...
272
273 ============================================================================
274 = Test suite
275
276 * Use "make check" and "make maintainer-check" liberally.
277
278 * Make sure each test file is executable.
279
280 * Export the 'keep_testdirs' environment variable to "yes" to keep
281   test directories for successful tests also.
282
283 * Use perl coverage information to ensure your new code is thoroughly
284   tested by your new tests.
285
286 * See file 't/README' for more information.
287
288 ============================================================================
289 = Release procedure
290
291 * The steps outlined here are meant to be followed for alpha and stable
292   releases as well.  Where differences are expected, they will be
293   explicitly described.
294
295 * Fetch new versions of the files that are maintained by the FSF by
296   running "make fetch".  In case any file in the automake repository
297   has been updated, commit and re-run the testsuite.
298
299 * Ensure that the copyright notices of the distributed files is up to
300   date.  The maintainer-only target "update-copyright" can help with
301   this.
302
303 * Check NEWS; in particular, ensure that all the relevant differences
304   with the last release are actually reported.
305
306 * Update the version number in configure.ac.
307   (The idea is that every other alpha number will be a net release.
308   The repository will always have its own "odd" number so we can easily
309   distinguish net and repo versions.)
310
311 * Run these commands, in this order:
312
313     make bootstrap
314     make check keep_testdirs=yes
315     make maintainer-check
316     make distcheck
317     make check-no-trailing-backslash-in-recipes
318     make check-cc-no-c-o
319
320   It is also advised to run "git clean -fdx" before invoking the
321   bootstrap, to ensure a really clean rebuild.  However, it must
322   be done carefully, because that command will remove *all* the
323   files that are not tracked by git!
324
325 * Run "make git-tag-release".
326   This will run the maintainer checks, verify that the local git
327   repository and working tree are clean and up-to-date, and create
328   a proper signed git tag for the release (based on the contents
329   of $(VERSION)).
330
331 * Run "make git-upload-release".
332   This will first verify that you are releasing from a tagged version
333   and that the local git repository and working tree are clean and
334   up-to-date, and will then run "make dist" to create the tarballs,
335   and invoke the 'gnupload' script sign and upload them to the correct
336   locations.  In case you need to sign with a non-default key, you can
337   use "make GNUPLOADFLAGS='--user KEY' git-upload-release".
338
339 * For stable releases you'll have to update the manuals at www.gnu.org.
340
341   - Generate manuals (with the help of the standard gendocs.sh script):
342
343        make web-manual
344
345     The ready-to-be-uploaded manuals (in several formats) will be left
346     in the 'doc/web-manuals' directory.
347
348   - Commit the updated manuals to web CVS:
349
350       make web-manual-update
351
352     If your local username is different from your username at Savannah,
353     you'll have to override the 'CVS_USER' make variable accordingly;
354     for example:
355
356       make web-manual-update CVS_USER=slattarini
357
358   - Check for link errors, fix them, recheck until convergence:
359     <http://validator.w3.org/checklink>
360
361 * Create an announcement message with "make announcement".  Edit the
362   generated 'announcement' file appropriately, in particularly filling
363   in by hand any "TODO" left in there.
364
365 * Update version number in configure.ac to next alpha number.
366   Re-run ./bootstrap.sh and commit.
367
368 * Don't forget to "git push" your changes so they appear in the public
369   git tree.
370
371 * Send the announcement generated in the earlier steps at least to
372   <autotools-announce@gnu.org> and <automake@gnu.org>.  If the release
373   is a stable one, the announcement must also go to <info-gnu@gnu.org>;
374   if it is an alpha or beta release, announcement should be sent also
375   to <platform-testers@gnu.org>, to maximize the possibility of early
376   testing on exotic or proprietary systems.  Finally, copy an abridged
377   version of the announcement into the NEWS feed at:
378   <https://savannah.gnu.org/projects/automake>.
379   Be sure to link a  version to the complete announcement (from
380   the version you sent to the automake list, as get archived on
381   <http://lists.gnu.org/archive/html/automake/>).
382
383 -----
384
385 Copyright (C) 2003-2013 Free Software Foundation, Inc.
386
387 This program is free software; you can redistribute it and/or modify
388 it under the terms of the GNU General Public License as published by
389 the Free Software Foundation; either version 2, or (at your option)
390 any later version.
391
392 This program is distributed in the hope that it will be useful,
393 but WITHOUT ANY WARRANTY; without even the implied warranty of
394 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
395 GNU General Public License for more details.
396
397 You should have received a copy of the GNU General Public License
398 along with this program.  If not, see <http://www.gnu.org/licenses/>.
399
400 Local Variables:
401 mode: text
402 End: