HACKING: miscellaneous fixes, updates and enhancements

Signed-off-by: Stefano Lattarini <stefano.lattarini@gmail.com>

1 files changed, 51 insertions, 51 deletions

diff --git a/HACKING b/HACKING
index 604bf676b..cebcb7246 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, 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
@@ -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