stable branches for Gnulib

[Bruno Haible]

Over the last two years or so, I've noticed that we quite frequently have
commits in Gnulib that fix regressions.

That is, while the documentation says
  "The goal is to have a 100% firm interface so that maintainers
   can feel free to update to the code in git at any time and know
   that their application will not break."
this is not always true in practice.

For example, Paul Smith writes in
<https://lists.gnu.org/archive/html/bug-make/2022-09/msg00005.html>:
  "I have an un-pushed commit that sets GNULIB_REVISION to avoid
   always pulling the latest gnulib version: we've seen build-from-git
   fail before due to changes in gnulib."

Additionally, the current situation is also a problem when making bug-
fix releases. I released GNU gettext 0.21 in 2000. Since the release
of glibc 2.35, in February 2022, this tarball does not compile any more on
Linux/ppc64le systems, due to conflicts in lib/cdefs.h or lib/libc-config.h.
So, I need to make a bug-fix release 0.21.1. But which Gnulib version to
use for it? It needs to incorporate the lib/cdefs.h fixes from May 2022,
but should *not* include the recent 'bootstrap' changes, nor the
work-in-progress around 'stdbool'. And it should not introduce portability
regressions compared to gettext 0.21.

There are essentially two ways improving this situation:

  (a) Do what the documentation says: "All experimental work should be done
      on [topic] branches".

  (b) Create stable branches, that accumulate bug fixes but are unlikely
      to contain breakage or regressions.

We haven't been doing (a), although it's in our documentation for more than
10 years. Obviously because new features are developed by a single developer,
and the size is not huge. That developer prefers to work with a series of up
to 10 patches, and use 'git rebase -i' to rework such a series, until he can
push all the series at once. In other words, topic branches are worth the
git branch management overhead only when the feature is so large that several
developers contribute or the single developer finds the patch series approach
impractical.

I'm therefore going for approach (b): Stable branches. So far, I've created
two stable branches
  - stable-202207: A stable branch that starts at the beginning of July 2022.
  - stable-202201: A stable branch that starts at the beginning of January 2022.
I intend to start a new stable branch every 6 months and maintain it for one
year.

Maintaining a stable branch is a small amount of work every month. It does
not even need to happen on a regular schedule. Even a schedule of 3 months
is OK.

This is the doc change that I am pushing.


2022-09-10  Bruno Haible  <bruno@clisp.org>

        doc: Mention the stable branches.
        * doc/gnulib-readme.texi (High Quality): Add subsection
        'Stable Branches'.
        (Writing reliable code): Extracted from 'High Quality'. Mention also
        -Wall and valgrind.

diff --git a/doc/gnulib-readme.texi b/doc/gnulib-readme.texi
index 492572799c..dcbdf2c8dd 100644
--- a/doc/gnulib-readme.texi
+++ b/doc/gnulib-readme.texi
@@ -539,18 +539,78 @@ We develop and maintain a testsuite for Gnulib.  The goal 
is to have a
 code in git at @emph{any} time and know that their application will not
 break.  This means that before any change can be committed to the
 repository, a test suite program must be produced that exposes the bug
-for regression testing.  All experimental work should be done on
-branches to help promote this.
+for regression testing.
+
+@node Stable Branches
+@subsection Stable Branches
+
+In Gnulib, we don't use topic branches for experimental work.
+Therefore, occasionally a broken commit may be pushed in Gnulib.
+It does not happen often, but it does happen.
+
+To compensate for this, Gnulib offers ``stable branches''.  These
+are branches of the Gnulib code that are maintained over some
+longer period (a year, for example) and include
+@itemize
+@item
+bug fixes,
+@item
+portability enhancements (to existing as well as to new platforms),
+@item
+updates to @code{config.guess} and @code{config.sub}.
+@end itemize
+
+@noindent
+Not included in the stable branches are:
+@itemize
+@item
+new features, such as new modules,
+@item
+optimizations,
+@item
+refactorings,
+@item
+complex or risky changes in general,
+@item
+updates to @code{texinfo.tex},
+@item
+documentation updates.
+@end itemize
+
+So far, we have two stable branches:
+@table @code
+@item stable-202207
+A stable branch that starts at the beginning of July 2022.
+@item stable-202201
+A stable branch that starts at the beginning of January 2022.
+@end table
+
+The two use-cases of stable branches are thus:
+@itemize
+@item
+You want to protect yourself from occasional breakage in Gnulib.
+@item
+When making a bug-fix release of your code, you can incorporate
+bug fixes in Gnulib, by pulling in the newest commits from the
+same stable branch that you were already using for the previous
+release.
+@end itemize
+
+@node Writing reliable code
+@subsection Writing reliable code
 
 When compiling and testing Gnulib and Gnulib-using programs, certain
-compiler options can help improve reliability.  The
-@code{manywarnings} module enables several forms of static checking in
-GCC and related compilers (@pxref{manywarnings}).  For dynamic checking,
-you can run @code{configure} with @code{CFLAGS} options appropriate
-for your compiler.  For example:
+compiler options can help improve reliability.  First of all, make it
+a habit to use @samp{-Wall} in all compilation commands. Beyond that,
+the @code{manywarnings} module enables several forms of static checking in
+GCC and related compilers (@pxref{manywarnings}).
+
+For dynamic checking, you can run @code{configure} with @code{CFLAGS}
+options appropriate for your compiler.  For example:
 
 @example
 ./configure \
+ CPPFLAGS='-Wall'\
  CFLAGS='-g3 -O2'\
 ' -D_FORTIFY_SOURCE=2'\
 ' -fsanitize=undefined'\
@@ -585,4 +645,7 @@ statically rather than dynamically, though this typically 
bloats the
 executable and the remaining extra libraries are still linked
 dynamically.
 
+It is also good to occasionally run the programs under @code{valgrind}
+(@pxref{Running self-tests under valgrind}).
+
 @include join-gnu.texi