From 97aaf121e92767dc06385d020dd30cdfaa86126f Mon Sep 17 00:00:00 2001 From: Stefano Lattarini Date: Sun, 17 Feb 2013 10:25:29 +0100 Subject: [PATCH] maint: 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 --- 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: * 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" -- 2.7.4