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.
============================================================================
= 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.
* 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.
* Don't use & for function calls, unless 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
should be added, and ideally, only trivial bugs, recent regressions,
or documentation issues should be addressed by them.
-* 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.
-
-* 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.
+* 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.
latest stable version of Autoconf installed and available early
in your PATH.
-* The Automake git tree currently carries three basic branches: 'maint',
- 'master' and 'next'.
+* The Automake git tree currently carries three basic branches: 'micro',
+ 'maint' and 'master'.
-* The 'maint' branch, reserved to changes that should go into the next
+* 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 'master' branch is where the development of the next minor release
+* 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 maint anyway).
+ absolute (emergency releases are cut from the 'micro' branch anyway).
-* The 'next' branch is reserved for the development of the next major
- release. Experimenting a little here is OK, 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
+* 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 'maint' branch should be kept regularly merged into the 'master'
- branch, and the 'master' branch into the 'next' branch. It is advisable
+* 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.
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 'master' branch is to be merged
- into the 'maint' branch, and then a "new" 'master' branch created
+* 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 'next' branch is to
- be merged into both the 'master' and 'maint' branch, and then "new"
- 'master' and 'next' branches 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
a later 'git log' gives an indication of which actual patches were
merged even when they don't appear early in the list.
-* The 'next', 'master' and 'maint' branches should not be rewound, i.e.,
+* 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.
+ the rewinding policy. It is usually a good idea to keep rewindable
+ branches in the 'experimental/*' "namespace"; i.e., give them names
+ like 'experimental/testsuite-work' or 'experimental/djgpp-for-WinNT'.
============================================================================
= Writing a good commit message
projects / platform / upstream / automake.git / commitdiff