Re: bug#13578: [IMPORTANT] A new versioning scheme for automake releases, and a new branching scheme for the Git repository

[Stefano Lattarini]

On 02/13/2013 07:39 PM, Stefano Lattarini wrote:
>
> Reference:
> <http://debbugs.gnu.org/cgi/bugreport.cgi?bug=13578>
>
> OK, so far I've seen only positive feedback about this proposal.  There
> are still some unresolved issues about how to handle beta releases; but
> the related proposals can be seen as a refinement of my scheme, not as
> something incompatible or in competition with it.  So I see no reason
> to hold back the implementation of my proposal on their account: we can
> implement those refinements later, once some consensus is reached and
> the details are worked out.
> 
> So, if I see no further objections, I'm going ahead with my proposal in
> a few days.
> 
Not yet; we first need a preparatory patch adjusting NEWS and HACKING (as
well as few miscellaneous comments in tests and scripts).  Then we can
finally proceed with the re-shuffling of the Git repository -- which I
guess will also have to be announced in autotools-announce at least, as
well as reported as a news on Savannah.

So here is my attempt; OK to push to branch-1.13.2?  I will proceed in a
couple of days if there is no objection.

Thanks,
  Stefano

---- 8< ---- 8< ---- 8< ---- 8< ---- 8< ---- 8< ---- 8< ---- 8< ----


>From 97aaf121e92767dc06385d020dd30cdfaa86126f Mon Sep 17 00:00:00 2001
Message-Id: <address@hidden>
From: Stefano Lattarini <address@hidden>
Date: Sun, 17 Feb 2013 10:25:29 +0100
Subject: [PATCH] describe new versioning and branching scheme, and adjust to it

See discussion about automake bug#13578 for more details and background.

Basically, for the versioning scheme:

  - micro versions only for bug and regression fixing;
  - minor versions for new backward-compatible features, and new
    non-fatal deprecations;
  - major versions for backward-incompatibilities, complex new
    features, and major refactoring.

And for the git branching scheme:

  + branch 'next' is for the upcoming major version;
  + branch 'master' is now for the upcoming minor version;
  + branch 'maint' is for the upcoming micro (bug-fixing) version;
  + the merging hierarchy is: 'maint' -> 'master' -> 'next'.

* HACKING (Automake versioning and compatibility scheme): New.
(Working with git): Adjust.
* NEWS: Update and fix.
* aclocal.in: Adjust some "FIXME" messages.
* automake.in: Likewise.
* m4/mkdirp.m4: Likewise.
* t/aclocal-acdir.sh: Likewise.
* t/aclocal-macrodir.tap: Likewise.
* t/aclocal-macrodirs.tap: Likewise.
* lib/Automake/Options.pm: Likewise.
* m4/internal/ac-config-macro-dirs.m4: Likewise.

Signed-off-by: Stefano Lattarini <address@hidden>
---
 HACKING                             | 100 +++++++++++++++++++++++++++++-------
 NEWS                                |  59 +++++++++++++++++----
 aclocal.in                          |   8 +--
 automake.in                         |  12 +++--
 lib/Automake/Options.pm             |   4 +-
 m4/internal/ac-config-macro-dirs.m4 |   2 +-
 m4/mkdirp.m4                        |   3 +-
 t/aclocal-acdir.sh                  |   2 +-
 t/aclocal-macrodir.tap              |   2 +-
 t/aclocal-macrodirs.tap             |   2 +-
 10 files changed, 150 insertions(+), 44 deletions(-)

diff --git a/HACKING b/HACKING
index c70143e..604bf67 100644
--- a/HACKING
+++ b/HACKING
@@ -93,6 +93,48 @@
   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.
+
+* 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.
+
+* 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,
@@ -103,22 +145,43 @@
   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: 'maint',
+  'master' and 'next'.
+
+* The 'maint' 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
+  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).
+
+* 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
+  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
+  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 'master' branch is to be merged
+  into the 'maint' branch, and then a "new" 'master' 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.

 * 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
@@ -126,15 +189,14 @@
   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.
+* For merges, 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 'next', 'master' and 'maint' 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.

 ============================================================================
 = Writing a good commit message
diff --git a/NEWS b/NEWS
index f9a1fb1..1ea9fa6 100644
--- a/NEWS
+++ b/NEWS
@@ -1,22 +1,59 @@
-New in 1.13.2:
+* WARNING: New versioning scheme for Automake.
+
+  - Starting with this version onward, Automake will use an update and
+    more rational versioning scheme, one that will allow users to know
+    which kind of changes can be expected from a new version, based on
+    its version number.
+
+    + Micro versions (e.g., 1.13.3, 2.0.1, 3.2.8) will introduce only
+      documentation updates and bug and regression fixes; they will
+      not introduce new features, nor any backward-incompatibility (any
+      such incompatibility would be considered a bug, to be fixed with
+      a further  micro release).
+
+    + Minor versions (e.g., 1.14, 2.1) can introduce new backward
+      compatible features; the only backward-incompatibilities allowed
+      in such a release are new *non-fatal* deprecations and warnings,
+      and possibly fixes for old or non-trivial bugs (or even inefficient
+      behaviours) that could unfortunately have been seen, and used, by
+      some developers as "corner case features".  This kind of fixes
+      should hopefully be quite rare.
+
+    + Major versions (now expected to be released every 18 or 24 months,
+      and not more often) can introduce new big features (possibly with
+      rough edges and not-fully-stabilized APIs), removal of deprecated
+      features, backward-incompatible changes of behaviour, and possibly
+      major refactorings (that, while ideally transparent to the user,
+      could introduce new bugs).  Incompatibilities should however not
+      be introduced gratuitously and abruptly; a proper deprecation path
+      should be duly implemented in the preceding minor releases.
+
+  - According to this new scheme, the next major version of Automake
+    (the one that has until now been labelled as '1.14') will actually
+    become "Automake 2.0".  Automake 1.14 will be the next minor version,
+    which will introduce new features and deprecation, but no backward
+    incompatibility.
+
+  - See discussion about automake bug#13578 for more details and
+    background: <http://debbugs.gnu.org/cgi/bugreport.cgi?bug=13578>

 * WARNING: Future backward-incompatibilities!

-  - Automake 1.14 will require Autoconf 2.70 or later (which is still
+  - Automake 2.0 will require Autoconf 2.70 or later (which is still
     unreleased at the moment of writing, but is planned to be released
-    before Automake 1.14 is).
+    before Automake 2.0 is).

-  - Automake 1.14 will drop support for the long-deprecated 'configure.in'
+  - Automake 2.0 will drop support for the long-deprecated 'configure.in'
     name for the Autoconf input file.  You are advised to start using the
     recommended name 'configure.ac' instead, ASAP.

   - The ACLOCAL_AMFLAGS special make variable will be fully deprecated
-    in Automake 1.14 (where it will raise warnings in the "obsolete"
+    in Automake 2.0 (where it will raise warnings in the "obsolete"
     category).  You are advised to start relying on the new Automake
     support for AC_CONFIG_MACRO_DIRS instead (which was introduced in
     Automake 1.13).

-  - Automake 1.14 will remove support for automatic dependency tracking
+  - Automake 2.0 will remove support for automatic dependency tracking
     with the SGI C/C++ compilers on IRIX.  The SGI depmode has been
     reported broken "in the wild" already, and we don't think investing
     time in debugging and fixing is worthwhile, especially considering
@@ -30,16 +67,20 @@ New in 1.13.2:
     modern Windows versions will continue to be fully supported.

   - Automake-provided scripts and makefile recipes might (finally!)
-    start assuming a POSIX shell in Automake 1.14.
+    start assuming a POSIX shell in Automake 2.0.

-  - Starting from Automake 1.14, third-party m4 files located in the
+  - Starting from Automake 2.0, third-party m4 files located in the
     system-wide aclocal directory, as well as in any directory listed
     in the ACLOCAL_PATH environment variable, will take precedence
     over "built-in" Automake macros.  For example (assuming Automake
     is installed in the /usr/local hierarchy), a definition of the
     AM_PROG_VALAC macro found in '/usr/local/share/aclocal/my-vala.m4'
     should take precedence over the same-named automake-provided macro
-    (defined in '/usr/local/share/aclocal-1.14/vala.m4').
+    (defined in '/usr/local/share/aclocal-2.0/vala.m4').
+
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+New in 1.13.2:

 * Obsolescent features:

diff --git a/aclocal.in b/aclocal.in
index b51c09d..82e9031 100644
--- a/aclocal.in
+++ b/aclocal.in
@@ -47,7 +47,7 @@ use File::Path ();
 # Some globals.

 # Support AC_CONFIG_MACRO_DIRS also with older autoconf.
-# FIXME: To be removed in Automake 1.14, once we can assume autoconf
+# FIXME: To be removed in Automake 2.0, once we can assume autoconf
 #        2.70 or later.
 # FIXME: keep in sync with 'internal/ac-config-macro-dirs.m4'.
 my $ac_config_macro_dirs_fallback =
@@ -744,7 +744,7 @@ sub trace_used_macros ()
   # a bug in option parsing code of autom4te 2.68 and earlier will cause
   # it to read standard input last, even if the "-" argument is specified
   # early.
-  # FIXME: To be removed in Automake 1.14, once we can assume autoconf
+  # FIXME: To be removed in Automake 2.0, once we can assume autoconf
   #        2.70 or later.
   $traces .= "$automake_includes[0]/internal/ac-config-macro-dirs.m4 ";

@@ -763,7 +763,7 @@ sub trace_used_macros ()
                     'AC_CONFIG_MACRO_DIR_TRACE',
                      # FIXME: Tracing the next two macros is a hack for
                      # compatibility with older autoconf.  Remove this in
-                     # Automake 1.14, when we can assume Autoconf 2.70 or
+                     # Automake 2.0, when we can assume Autoconf 2.70 or
                      # later.
                     'AC_CONFIG_MACRO_DIR',
                     '_AM_CONFIG_MACRO_DIRS')),
@@ -820,7 +820,7 @@ sub trace_used_macros ()
   # FIXME: in Autoconf >= 2.70, AC_CONFIG_MACRO_DIR calls
   # AC_CONFIG_MACRO_DIR_TRACE behind the scenes, which could
   # leave unwanted duplicates in @ac_config_macro_dirs.
-  # Remove this in Automake 1.14, when we'll stop tracing
+  # Remove this in Automake 2.0, when we'll stop tracing
   # AC_CONFIG_MACRO_DIR explicitly.
   @ac_config_macro_dirs = uniq @ac_config_macro_dirs;

diff --git a/automake.in b/automake.in
index 9ed3507..0c2ab3d 100644
--- a/automake.in
+++ b/automake.in
@@ -2131,7 +2131,7 @@ sub handle_source_transform ($$$$%)
        msg_var ('unsupported', $ext_var, $ext_var->name . " can assume at most 
one value")
          if $default_source_ext =~ /[\t ]/;
        (my $default_source = $unxformed) =~ 
s,(\.[^./\\]*)?$,$default_source_ext,;
-       # TODO: Remove this backward-compatibility hack in Automake 1.14.
+       # TODO: Remove this backward-compatibility hack in Automake 2.0.
        if ($old_default_source ne $default_source
            && !$ext_var
            && (rule $old_default_source
@@ -4146,8 +4146,8 @@ sub handle_configure ($$$@)
   # Distribute and define mkinstalldirs only if it is already present
   # in the package, for backward compatibility (some people may still
   # use $(mkinstalldirs)).
-  # TODO: start warning about this in Automake 1.13.2, and have
-  # TODO: Automake 1.14 or 1.15 drop it (and the mkinstalldirs script
+  # TODO: start warning about this in Automake 1.14, and have
+  # TODO: Automake 2.0 drop it (and the mkinstalldirs script
   # TODO: as well).
   my $mkidpath = "$config_aux_dir/mkinstalldirs";
   if (-f $mkidpath)
@@ -5144,7 +5144,7 @@ sub scan_autoconf_traces ($)
                AC_REQUIRE_AUX_FILE => 1,
                AC_SUBST_TRACE => 1,
                AM_AUTOMAKE_VERSION => 1,
-                AM_PROG_MKDIR_P => 0, # FIXME: to be removed in 1.14
+                AM_PROG_MKDIR_P => 0,
                AM_CONDITIONAL => 2,
                AM_EXTRA_RECURSIVE_TARGETS => 1,
                AM_GNU_GETTEXT => 0,
@@ -5300,8 +5300,10 @@ sub scan_autoconf_traces ($)

          $seen_automake_version = 1;
        }
-      elsif ($macro eq 'AM_PROG_MKDIR_P') # FIXME: to be removed in 1.14
+      elsif ($macro eq 'AM_PROG_MKDIR_P')
        {
+          # FIXME: we are no longer going to remove this! adjust warning
+          # FIXME: message accordingly.
          msg 'obsolete', $where, <<'EOF';
 The 'AM_PROG_MKDIR_P' macro is deprecated, and will soon be removed.
 You should use the Autoconf-provided 'AC_PROG_MKDIR_P' macro instead,
diff --git a/lib/Automake/Options.pm b/lib/Automake/Options.pm
index 3674920..cfeb78e 100644
--- a/lib/Automake/Options.pm
+++ b/lib/Automake/Options.pm
@@ -315,7 +315,7 @@ sub _process_option_list (\%@)
         {
           set_strictness ($_);
         }
-      # TODO: Remove this special check in Automake 1.14 or 1.15.
+      # TODO: Remove this special check in Automake 3.0.
       elsif (/^(.*\/)?ansi2knr$/)
         {
           # Obsolete (and now removed) de-ANSI-fication support.
@@ -327,7 +327,7 @@ sub _process_option_list (\%@)
         {
           error $where, "support for Cygnus-style trees has been removed";
         }
-      # TODO: Remove this special check in Automake 1.14 or 1.15.
+      # TODO: Remove this special check in Automake 3.0.
       elsif ($_ eq 'dist-lzma')
         {
           error ($where, "support for lzma-compressed distribution " .
diff --git a/m4/internal/ac-config-macro-dirs.m4 
b/m4/internal/ac-config-macro-dirs.m4
index 4ddcef3..2684883 100644
--- a/m4/internal/ac-config-macro-dirs.m4
+++ b/m4/internal/ac-config-macro-dirs.m4
@@ -1,5 +1,5 @@
 # Support AC_CONFIG_MACRO_DIRS with older autoconf.     -*- Autoconf -*-
-# FIXME: To be removed in Automake 1.14, once we can assume autoconf
+# FIXME: To be removed in Automake 2.0, once we can assume autoconf
 #        2.70 or later.
 # FIXME: keep in sync with the contents of the variable
 #        '$ac_config_macro_dirs_fallback' in aclocal.in.
diff --git a/m4/mkdirp.m4 b/m4/mkdirp.m4
index 68f44cb..0b90d2c 100644
--- a/m4/mkdirp.m4
+++ b/m4/mkdirp.m4
@@ -11,7 +11,8 @@
 AC_DEFUN([AM_PROG_MKDIR_P],
 [AC_PREREQ([2.60])dnl
 AC_REQUIRE([AC_PROG_MKDIR_P])dnl
-dnl FIXME to be removed in Automake 1.14.
+dnl FIXME we are no longer going to remove this! adjust warning
+dnl FIXME message accordingly.
 AC_DIAGNOSE([obsolete],
 [$0: this macro is deprecated, and will soon be removed.
 You should use the Autoconf-provided 'AC][_PROG_MKDIR_P' macro instead,
diff --git a/t/aclocal-acdir.sh b/t/aclocal-acdir.sh
index 7fbb27a..80eba31 100755
--- a/t/aclocal-acdir.sh
+++ b/t/aclocal-acdir.sh
@@ -21,7 +21,7 @@
 . test-init.sh

 mkdir am sys
-# FIXME: remove in Automake 1.14.
+# FIXME: remove in Automake 2.0
 mkdir am/internal
 : > am/internal/ac-config-macro-dirs.m4

diff --git a/t/aclocal-macrodir.tap b/t/aclocal-macrodir.tap
index 3c66e53..44af05f 100755
--- a/t/aclocal-macrodir.tap
+++ b/t/aclocal-macrodir.tap
@@ -174,7 +174,7 @@ test_end
 #---------------------------------------------------------------------------

 # Avoid spurious failures with pre-2.70 autoconf.
-# FIXME: remove this in automake 1.14, once we require Autoconf 2.70.
+# FIXME: remove this in automake 2.0, once we require Autoconf 2.70.
 if echo 'AC_INIT AC_CONFIG_MACRO_DIRS' | $AUTOCONF -o/dev/null -; then

   test_begin "AC_CONFIG_MACRO_DIR interaction with AC_REQUIRE"
diff --git a/t/aclocal-macrodirs.tap b/t/aclocal-macrodirs.tap
index 89e424d..ac594bb 100755
--- a/t/aclocal-macrodirs.tap
+++ b/t/aclocal-macrodirs.tap
@@ -373,7 +373,7 @@ test_end
 #---------------------------------------------------------------------------

 # Avoid spurious failures with pre-2.70 autoconf.
-# FIXME: remove this in automake 1.14, once we require Autoconf 2.70.
+# FIXME: remove this in automake 2.0, once we require Autoconf 2.70.
 if echo 'AC_INIT AC_CONFIG_MACRO_DIRS' | $AUTOCONF -o/dev/null -; then

   test_begin "AC_CONFIG_MACRO_DIRS interaction with AC_REQUIRE"
-- 
1.8.1.1.701.g02339dd