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 <stefano.lattarini@gmail.com>
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,
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
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
-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
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:
# 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 =
# 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 ";
'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')),
# 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;
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
# 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)
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,
$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,
{
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.
{
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 " .
# 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.
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,
. 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
#---------------------------------------------------------------------------
# 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"
#---------------------------------------------------------------------------
# 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"