From 97aaf121e92767dc06385d020dd30cdfaa86126f Mon Sep 17 00:00:00 2001 From: Stefano Lattarini Date: Sun, 17 Feb 2013 10:25:29 +0100 Subject: 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 ++++++++++++++++++++++++++++++++++++++++++++++++++++------------ 1 file changed, 81 insertions(+), 19 deletions(-) (limited to 'HACKING') diff --git a/HACKING b/HACKING index c70143ef7..604bf676b 100644 --- a/HACKING +++ b/HACKING @@ -92,6 +92,48 @@ &, just convert the old code as you work on it, and write new 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 @@ -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 -- cgit v1.2.1