-================================================================
+============================================================================
= 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
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
+ - 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
- and in the test case you write. Put him into THANKS.
+ 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
which should be updated by hand whenever the GPL gets updated (which
shouldn't happen that often anyway :-)
-* Changes other than bug fixes must be mentioned in NEWS. Important
- bug fixes should be mentioned in NEWS, too.
+* 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 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.
+* 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_SUBST.
+ 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 ${...}
-* Use ':', not 'true'. Use 'exit 1', not 'false'.
+* Prefer ':' over 'true', mostly for consistency with existing code.
-* Use '##' comments liberally. Comment anything even remotely
- unusual.
+* Use '##' comments liberally. Comment anything even remotely unusual.
-* Never use basename or dirname. Instead use sed.
+* 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.
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.
+ 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
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 required.
+* Don't use & for function calls, unless really required.
The use of & prevents prototypes from being checked.
- Just as above, don't change massively all the code to strip the
- &, just convert the old code as you work on it, and write new
- code without.
-================================================================
+============================================================================
+= 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.
+
+ 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,
latest stable version of Autoconf installed and available early
in your PATH.
-* The Automake git tree currently carries two basic branches: 'master' for
- the current development, and 'maint' for maintenance and bug fixes. The
- maint branch should be kept regularly merged 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.
+* 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.
- in the future, we might introduce a special branch named 'next' that
- may serve as common ground for feature merging and testing, should
- they not yet be ready for master.
-* After a major release is done, the master branch is to be merged into
- the maint branch, and then a "new" master branch created stemming
- from the resulting commit.
+* 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
the active branches descending from the buggy commit. This offers a
simple way to fix the bug consistently and effectively.
-* For merges from branches other than maint, 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.
+* 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.
-* master and release branches should not be rewound, i.e., should always
- fast-forward, except maybe for privacy issues. The maint branch should not
- be rewound except maybe after retiring a release branch or a new stable
- release. For next, and for feature branches, the announcement for the
- branch should document rewinding policy.
+* 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
<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 is
- optional, but you are expected to provide it more often than not.
+ 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.
<detailed list of touched files>
-* The <detailed list of touched files> is mandatory but for the most
- trivial changes, and should follows the GNU guidelines for ChangeLog
- entries (described explicitly in the GNU Coding Standards); it might
- be something of this sort:
+* 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.
... 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.
-* Make sure each test file is executable.
-
* Export the 'keep_testdirs' environment variable to "yes" to keep
test directories for successful tests also.
* See file 't/README' for more information.
-================================================================
+============================================================================
= Release procedure
* The steps outlined here are meant to be followed for alpha and stable
date. The maintainer-only target "update-copyright" can help with
this.
-* Update NEWS.
+* 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 this:
- ./bootstrap.sh && ./configure && make && make check && make distcheck
+* 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, check that the NEWS file is
- up-to-date, check 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)).
+ 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
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.sh and commit.
* Don't forget to "git push" your changes so they appear in the public
git tree.
-* For stable releases, update the manuals at www.gnu.org:
- - Generate manuals:
- cd doc
- wget "http://savannah.gnu.org/cgi-bin/viewcvs/~checkout~/texinfo/texinfo/util/gendocs.sh"
- wget "http://savannah.gnu.org/cgi-bin/viewcvs/~checkout~/texinfo/texinfo/util/gendocs_template"
- sh ./gendocs.sh --email bug-automake@gnu.org automake "GNU Automake"
- - copy manuals recursively to web cvs,
- - commit.
- - Check for link errors, fix them, recheck until convergence:
- <http://validator.w3.org/checklink>
-
-* Send the announcement 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 the announcement into the NEWS feed at
+* 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-2012 Free Software Foundation, Inc.
+Copyright (C) 2003-2013 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
projects / platform / upstream / automake.git / blobdiff