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 <[email protected]> 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
