]> Savannah Git Hosting - gnulib.git/commitdiff
doc: Mention the stable branches.
authorBruno Haible <bruno@clisp.org>
Sat, 10 Sep 2022 13:17:05 +0000 (15:17 +0200)
committerBruno Haible <bruno@clisp.org>
Sat, 10 Sep 2022 13:17:31 +0000 (15:17 +0200)
* doc/gnulib-readme.texi (High Quality): Add subsection
'Stable Branches'.
(Writing reliable code): Extracted from 'High Quality'. Mention also
-Wall and valgrind.

ChangeLog
doc/gnulib-readme.texi

index 47b05390f6c33e1f3a092a0566472d96a5d96c7b..4e29c49bda9d469cd9b1637032c88aa079bebbd2 100644 (file)
--- a/ChangeLog
+++ b/ChangeLog
@@ -1,3 +1,11 @@
+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.
+
 2022-09-09  Bruno Haible  <bruno@clisp.org>
 
        posix_spawn-internal: Optimize DuplicateHandle calls on native Windows.
index 492572799ccd34cef90ba2b00a5103731ef55c11..dcbdf2c8ddd7cc139ddc481d94391a140e2bef40 100644 (file)
@@ -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