> - 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.
This looks like a typo - should the "s" be there? On Wed, May 15, 2013 at 8:20 PM, Stefano Lattarini <stefano.lattar...@gmail.com> wrote: > Signed-off-by: Stefano Lattarini <stefano.lattar...@gmail.com> > --- > HACKING | 102 > ++++++++++++++++++++++++++++++++-------------------------------- > 1 file changed, 51 insertions(+), 51 deletions(-) > > diff --git a/HACKING b/HACKING > index 604bf67..606702f 100644 > --- a/HACKING > +++ b/HACKING > @@ -12,16 +12,16 @@ > 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, an 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 > @@ -35,19 +35,18 @@ > 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. > @@ -57,12 +56,11 @@ > > * 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. > @@ -71,9 +69,9 @@ > 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. > @@ -88,9 +86,6 @@ > > * 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 > @@ -118,18 +113,21 @@ > 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. > @@ -145,30 +143,30 @@ > 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. > > @@ -176,12 +174,12 @@ > 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 > @@ -193,10 +191,12 @@ > 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 > -- > 1.8.3.rc2 > >