405 lines
17 KiB
Plaintext
405 lines
17 KiB
Plaintext
============================================================================
|
|
= This file
|
|
|
|
* This file attempts to describe the rules to use when hacking
|
|
automake.
|
|
|
|
============================================================================
|
|
= Administrivia
|
|
|
|
* 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.
|
|
|
|
* If you incorporate a change from somebody on the net:
|
|
- First, if it is a large change, you must make sure they have
|
|
signed the appropriate paperwork.
|
|
- Second, be sure to add their name and email address to THANKS.
|
|
|
|
* If a change fixes a test, mention the test in the commit message.
|
|
If a change fixes a bug registered in the Automake debbugs tracker,
|
|
mention the bug number in the commit message.
|
|
|
|
* If somebody reports a new bug, mention his name in the commit message
|
|
that fixes or exposes the bug, and put him into THANKS.
|
|
|
|
* When documenting a non-trivial idiom or example in the manual, be
|
|
sure to add a test case for it, and to reference such test case from
|
|
a proper Texinfo comment.
|
|
|
|
* Some files in the automake package are not owned by automake; these
|
|
files are listed in the $(FETCHFILES) variable in Makefile.am. They
|
|
should never be edited here. Almost all of them can be updated from
|
|
respective upstreams with "make fetch" (this should be done especially
|
|
before releases). The only exception is the 'lib/COPYING' (from FSF),
|
|
which should be updated by hand whenever the GPL gets updated (which
|
|
shouldn't happen that often anyway :-)
|
|
|
|
* Changes other than *trivial* bug fixes must be mentioned in NEWS.
|
|
|
|
* Changes which are potentially controversial, require a non-trivial
|
|
plan, or must be implemented gradually with a roadmap spanning several
|
|
releases (either minor or major) should be discussed on the list,
|
|
and have a proper entry in the PLANS directory. This entry should be
|
|
always committed in the "maint" branch, even if the change it deals
|
|
with is only for the master branch, or a topic branch. Usually, in
|
|
addition to this, it is useful to open a "wishlist" report on the
|
|
Automake debbugs tracker, to keep the idea more visible, and have the
|
|
discussions surrounding it easily archived in a central place.
|
|
|
|
============================================================================
|
|
= Naming
|
|
|
|
* We've adopted the convention that internal AC_SUBSTs and make variables
|
|
should be named with a leading 'am__', and internally generated targets
|
|
should be named with a leading 'am--'. This convention, although in
|
|
place from at least February 2001, isn't yet universally used.
|
|
But all new code should use it.
|
|
|
|
We used to use '_am_' as the prefix for an internal AC_SUBSTs.
|
|
However, it turns out that NEWS-OS 4.2R complains if a Makefile
|
|
variable begins with the underscore character. Yay for them.
|
|
I changed the target naming convention just to be safe.
|
|
|
|
============================================================================
|
|
= Editing '.am' files
|
|
|
|
* Always use $(...) and not ${...}
|
|
|
|
* Prefer ':' over 'true', mostly for consistency with existing code.
|
|
|
|
* Use '##' comments liberally. Comment anything even remotely unusual.
|
|
|
|
* Never use basename or dirname. Instead, use sed.
|
|
|
|
* Do not use 'cd' within back-quotes, use '$(am__cd)' instead.
|
|
Otherwise the directory name may be printed, depending on CDPATH.
|
|
More generally, do not ever use plain 'cd' together with a relative
|
|
directory that does not start with a dot, or you might end up in one
|
|
computed with CDPATH.
|
|
|
|
* For install and uninstall rules, if a loop is required, it should be
|
|
silent. Then the body of the loop itself should print each "important"
|
|
command it runs. The printed commands should be preceded by a single
|
|
space.
|
|
|
|
* Ensure install rules do not create any installation directory where
|
|
nothing is to be actually installed. See automake bug#11030.
|
|
|
|
============================================================================
|
|
= Editing automake.in and aclocal.in
|
|
|
|
* Indent using GNU style. For historical reasons, the perl code
|
|
contains portions indented using Larry Wall's style (perl-mode's
|
|
default), and other portions using the GNU style (cperl-mode's
|
|
default). Write new code using GNU style.
|
|
|
|
* Don't use & for function calls, unless really required.
|
|
The use of & prevents prototypes from being checked.
|
|
|
|
============================================================================
|
|
= Automake versioning and compatibility scheme
|
|
|
|
* There are three kinds of automake releases:
|
|
|
|
- new major releases (e.g., 2.0, 5.0)
|
|
- new minor releases (e.g., 1.14, 2.1)
|
|
- micro a.k.a. "bug-fixing" releases (e.g., 1.13.2, 2.0.1, 3.5.17).
|
|
|
|
A new major release should have the major version number bumped, and
|
|
the minor and micro version numbers reset to zero. A new minor release
|
|
should have the major version number unchanged, the minor version number
|
|
bumped, and the micro version number reset to zero. Finally, a new
|
|
micro version should have the major and minor version numbers unchanged,
|
|
and the micro version number bumped by one.
|
|
|
|
For example, the first minor version after 1.13.2 will be 1.14; the
|
|
first bug-fixing version after 1.14 that will be 1.14.1; the first
|
|
new major version after all such releases will be 2.0; the first
|
|
bug-fixing version after 2.0 will be 2.0.1; and a further bug-fixing
|
|
version after 2.0.1 will be 2.0.2.
|
|
|
|
* Micro releases should be just bug-fixing releases; no new features
|
|
should be added, and ideally, only trivial bugs, recent regressions,
|
|
or documentation issues should be addressed by them. On the other
|
|
hand, it's OK to include testsuite work and even testsuite refactoring
|
|
in a micro version, since a regression there is not going to annoy or
|
|
inconvenience Automake users, but only the Automake developers.
|
|
|
|
* Minor releases can introduce new "safe" features, do non-trivial but
|
|
mostly safe code clean-ups, and even add new runtime warnings (rigorously
|
|
non-fatal). But they shouldn't include any backward incompatible change,
|
|
nor contain any potentially destabilizing refactoring or sweeping change,
|
|
nor introduce new features whose implementation might be liable to cause
|
|
bugs or regressions in existing code. However, it might be acceptable to
|
|
introduce very limited and localized backward-incompatibilities, *only*
|
|
if that is necessary to fix non-trivial bugs, address serious performance
|
|
issues, or greatly enhance usability. But please, do this sparsely and
|
|
rarely!
|
|
|
|
* Major releases can introduce backward-incompatibilities (albeit such
|
|
incompatibilities should be announced well in advance, and a smooth
|
|
transition plan prepared for them), and try more risking and daring
|
|
refactorings and code cleanups.
|
|
|
|
* For more information, refer to the extensive discussion associated
|
|
with automake bug#13578.
|
|
|
|
============================================================================
|
|
= Working with git
|
|
|
|
* To regenerate dependent files created by aclocal and automake,
|
|
use the 'bootstrap' script. It uses the code from the source
|
|
tree, so the resulting files (aclocal.m4 and Makefile.in) should
|
|
be the same as you would get if you install this version of
|
|
automake and use it to generate those files. Be sure to have the
|
|
latest stable version of Autoconf installed and available early
|
|
in your PATH.
|
|
|
|
* The Automake git tree currently carries three basic branches: 'micro',
|
|
'maint' and 'master'.
|
|
|
|
* The 'micro' branch, reserved to changes that should go into the next
|
|
micro release; so it will just see fixes for regressions, trivial
|
|
bugs, or documentation issues, and no "active" development whatsoever.
|
|
Since emergency regression-fixing or security releases could be cut
|
|
from this branch at any time, it should always be kept in a releasable
|
|
state.
|
|
|
|
* The 'maint' branch is where the development of the next minor release
|
|
takes place. It should be kept in a stable, almost-releasable state,
|
|
to simplify testing and deploying of new minor version. Note that
|
|
this is not a hard rule, and such "stability" is not expected to be
|
|
absolute (emergency releases are cut from the 'micro' branch anyway).
|
|
|
|
* The 'master' branch is reserved for the development of the next major
|
|
release. Experimenting a little is OK here, but don't let the branch
|
|
grow too unstable; if you need to do exploratory programming or
|
|
over-arching change, you should use a dedicated topic branch, and
|
|
only merge that back once it is reasonably stable.
|
|
|
|
* The 'micro' branch should be kept regularly merged into the 'maint'
|
|
branch, and the 'maint' branch into the 'master' branch. It is advisable
|
|
to merge only after a set of related commits have been applied, to avoid
|
|
introducing too much noise in the history.
|
|
|
|
* There may be a number of longer-lived feature branches for new
|
|
developments. They should be based off of a common ancestor of all
|
|
active branches to which the feature should or might be merged later.
|
|
|
|
* After a new minor release is done, the 'maint' branch is to be merged
|
|
into the 'micro' branch, and then a "new" 'maint' branch created
|
|
stemming from the resulting commit.
|
|
Similarly, after a new major release is done, the 'master' branch is to
|
|
be merged into both the 'micro' and 'maint' branches, and then "new"
|
|
'master' branch created stemming from the resulting commit.
|
|
|
|
* When fixing a bug (especially a long-standing one), it may be useful
|
|
to commit the fix to a new temporary branch based off the commit that
|
|
introduced the bug. Then this "bugfix branch" can be merged into all
|
|
the active branches descending from the buggy commit. This offers a
|
|
simple way to fix the bug consistently and effectively.
|
|
|
|
* When merging, prefer 'git merge --log' over plain 'git merge', so that
|
|
a later 'git log' gives an indication of which actual patches were
|
|
merged even when they don't appear early in the list.
|
|
|
|
* The 'master', 'maint' and 'micro' branches should not be rewound, i.e.,
|
|
should always fast-forward, except maybe for privacy issues. For
|
|
feature branches, the announcement for the branch should document
|
|
the rewinding policy.
|
|
If a topic branch is expected to be rewound, it is good practice to put
|
|
it in the 'experimental/*' namespace; for example, a rewindable branch
|
|
dealing with Vala support could be named like "experimental/vala-work".
|
|
|
|
============================================================================
|
|
= Writing a good commit message
|
|
|
|
* Here is the general format that Automake's commit messages are expected
|
|
to follow. See the further points below for clarifications and minor
|
|
corrections.
|
|
|
|
topic: brief description (this is the "summary line")
|
|
|
|
<reference to relevant bugs, if any>
|
|
|
|
Here goes a more detailed explanation of why the commit is needed,
|
|
and a general overview of what it does, and how. This section
|
|
should almost always be provided, possibly only with the expection
|
|
of obvious fixes or very trivial changes.
|
|
|
|
And if the detailed explanation is quite long or detailed, you can
|
|
want to break it in more paragraphs.
|
|
|
|
Then you can add references to relevant mailing list discussions
|
|
(if any), with proper links. But don't take this as an excuse for
|
|
writing incomplete commit messages! The "distilled" conclusions
|
|
reached in such discussions should have been placed in the
|
|
paragraphs above.
|
|
|
|
Finally, here you can thank people that motivated or helped the
|
|
change. So, thanks to John Doe for bringing up the issue, and to
|
|
J. Random Hacker for providing suggestions and testing the patch.
|
|
|
|
<detailed list of touched files>
|
|
|
|
* The <detailed list of touched files> should usually be provided (but
|
|
for short or trivial changes), and should follow the GNU guidelines
|
|
for ChangeLog entries (described explicitly in the GNU Coding
|
|
Standards); it might be something of this sort:
|
|
|
|
* some/file (func1): Improved frobnication.
|
|
(func2): Adjusted accordingly.
|
|
* another/file (foo, bar): Likewise.
|
|
* tests/foo.tap: New test.
|
|
* tests/Makefile.am (TESTS): Add it.
|
|
|
|
* If your commit fixes an automake bug registered in the tracker (say
|
|
numbered 1234), you should put the following line after the summary
|
|
line:
|
|
|
|
This change fixes automake bug#1234.
|
|
|
|
* If your commit is just related to the given bug report, but does not
|
|
fix it, you might want to add a line like this instead:
|
|
|
|
This change is related to automake bug#1234.
|
|
|
|
* When referring to older commits, use 'git describe' output as pointer.
|
|
But also try to identify the given commit by date and/or summary line
|
|
if possible. Examples:
|
|
|
|
Since yesterday's commit, v1.11-2019-g4d2bf42, ...
|
|
|
|
... removed in commit 'v1.11-1674-g02e9072' of 01-01-2012,
|
|
"dist: ditch support for lzma"...
|
|
|
|
============================================================================
|
|
= Test suite
|
|
|
|
* Use "make check" and "make maintainer-check" liberally.
|
|
|
|
* Export the 'keep_testdirs' environment variable to "yes" to keep
|
|
test directories for successful tests also.
|
|
|
|
* Use perl coverage information to ensure your new code is thoroughly
|
|
tested by your new tests.
|
|
|
|
* See file 't/README' for more information.
|
|
|
|
============================================================================
|
|
= Release procedure
|
|
|
|
* The steps outlined here are meant to be followed for alpha and stable
|
|
releases as well. Where differences are expected, they will be
|
|
explicitly described.
|
|
|
|
* Fetch new versions of the files that are maintained by the FSF by
|
|
running "make fetch". In case any file in the automake repository
|
|
has been updated, commit and re-run the testsuite.
|
|
|
|
* Ensure that the copyright notices of the distributed files is up to
|
|
date. The maintainer-only target "update-copyright" can help with
|
|
this.
|
|
|
|
* Check NEWS; in particular, ensure that all the relevant differences
|
|
with the last release are actually reported.
|
|
|
|
* Update the version number in configure.ac.
|
|
(The idea is that every other alpha number will be a net release.
|
|
The repository will always have its own "odd" number so we can easily
|
|
distinguish net and repo versions.)
|
|
|
|
* Run these commands, in this order:
|
|
|
|
make bootstrap
|
|
make check keep_testdirs=yes
|
|
make maintainer-check
|
|
make distcheck
|
|
make check-no-trailing-backslash-in-recipes
|
|
make check-cc-no-c-o
|
|
|
|
It is also advised to run "git clean -fdx" before invoking the
|
|
bootstrap, to ensure a really clean rebuild. However, it must
|
|
be done carefully, because that command will remove *all* the
|
|
files that are not tracked by git!
|
|
|
|
* Run "make git-tag-release".
|
|
This will run the maintainer checks, verify that the local git
|
|
repository and working tree are clean and up-to-date, and create
|
|
a proper signed git tag for the release (based on the contents
|
|
of $(VERSION)).
|
|
|
|
* Run "make git-upload-release".
|
|
This will first verify that you are releasing from a tagged version
|
|
and that the local git repository and working tree are clean and
|
|
up-to-date, and will then run "make dist" to create the tarballs,
|
|
and invoke the 'gnupload' script sign and upload them to the correct
|
|
locations. In case you need to sign with a non-default key, you can
|
|
use "make GNUPLOADFLAGS='--user KEY' git-upload-release".
|
|
|
|
* For stable releases you'll have to update the manuals at www.gnu.org.
|
|
|
|
- Generate manuals (with the help of the standard gendocs.sh script):
|
|
|
|
make web-manual
|
|
|
|
The ready-to-be-uploaded manuals (in several formats) will be left
|
|
in the 'doc/web-manuals' directory.
|
|
|
|
- Commit the updated manuals to web CVS:
|
|
|
|
make web-manual-update
|
|
|
|
If your local username is different from your username at Savannah,
|
|
you'll have to override the 'CVS_USER' make variable accordingly;
|
|
for example:
|
|
|
|
make web-manual-update CVS_USER=slattarini
|
|
|
|
- Check for link errors, fix them, recheck until convergence:
|
|
<http://validator.w3.org/checklink>
|
|
|
|
* Create an announcement message with "make announcement". Edit the
|
|
generated 'announcement' file appropriately, in particularly filling
|
|
in by hand any "TODO" left in there.
|
|
|
|
* Update version number in configure.ac to next alpha number.
|
|
Re-run ./bootstrap and commit.
|
|
|
|
* Don't forget to "git push" your changes so they appear in the public
|
|
git tree.
|
|
|
|
* Send the announcement generated in the earlier steps at least to
|
|
<autotools-announce@gnu.org> and <automake@gnu.org>. If the release
|
|
is a stable one, the announcement must also go to <info-gnu@gnu.org>;
|
|
if it is an alpha or beta release, announcement should be sent also
|
|
to <platform-testers@gnu.org>, to maximize the possibility of early
|
|
testing on exotic or proprietary systems. Finally, copy an abridged
|
|
version of the announcement into the NEWS feed at:
|
|
<https://savannah.gnu.org/projects/automake>.
|
|
Be sure to link a version to the complete announcement (from
|
|
the version you sent to the automake list, as get archived on
|
|
<http://lists.gnu.org/archive/html/automake/>).
|
|
|
|
-----
|
|
|
|
Copyright (C) 2003-2017 Free Software Foundation, Inc.
|
|
|
|
This program 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 2, or (at your option)
|
|
any later version.
|
|
|
|
This program 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 <http://www.gnu.org/licenses/>.
|
|
|
|
Local Variables:
|
|
mode: text
|
|
End:
|