Re: [FYI] {branch-1.13.2} HACKING: miscellaneous fixes, updates and enhancements

[Gavin Smith]

> -  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
<address@hidden> wrote:
> Signed-off-by: Stefano Lattarini <address@hidden>
> ---
>  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
>
>