doc: Add maintainer-makefile section to manual.

Suggested by Simon Josefsson <simon@josefsson.org> in
<https://lists.gnu.org/r/bug-gnulib/2025-11/msg00178.html>.

* doc/maintainer-makefile.texi: New file documenting
maintainer-makefile targets and supported NEWS formats.
* doc/gnulib.texi (Build Infrastructure Modules): Include it here.
(Release Management Files): Tweak grammar.

Signed-off-by: Simon Josefsson <simon@josefsson.org>

diff --git a/ChangeLog b/ChangeLog
index fd84a37e83228bbc1c8ae686d28fd32ba3422bad..9d7e439c2b2668ab09e7fd9a3b5f8732910914c1 100644 (file)
--- a/ChangeLog
+++ b/ChangeLog
@@ -1,3 +1,13 @@
+2025-12-04  Basil L. Contovounesios  <basil@contovou.net>
+
+       doc: Add maintainer-makefile section to manual.
+       Suggested by Simon Josefsson <simon@josefsson.org> in
+       <https://lists.gnu.org/r/bug-gnulib/2025-11/msg00178.html>.
+       * doc/maintainer-makefile.texi: New file documenting
+       maintainer-makefile targets and supported NEWS formats.
+       * doc/gnulib.texi (Build Infrastructure Modules): Include it here.
+       (Release Management Files): Tweak grammar.
+
 2026-01-12  Bruno Haible  <bruno@clisp.org>
 
        obstack-printf-posix: Improve comment.

diff --git a/doc/gnulib.texi b/doc/gnulib.texi
index 53280662559025b1ac8540050f10afefbed7a561..94c1c0dba0bc81882719651a6540bd4f3dc1c4da 100644 (file)
--- a/doc/gnulib.texi
+++ b/doc/gnulib.texi
@@ -8227,6 +8227,7 @@ for use with GNU Automake (in particular).
 * Package version management::
 * VCS To ChangeLog::
 * gitlog-to-changelog::
+* maintainer-makefile::
 @end menu
 
 @include havelib.texi
@@ -8249,6 +8250,8 @@ for use with GNU Automake (in particular).
 
 @include gitlog-to-changelog.texi
 
+@include maintainer-makefile.texi
+
 
 @node Build Infrastructure Files
 @chapter Build Infrastructure Files
@@ -8473,9 +8476,9 @@ test suite on Android.
 @node Release Management Files
 @chapter Release Management Files
 
-Gnulib also contain a few scripts that are useful for the release
+Gnulib also contains a few scripts that are useful for the release
 management of a package.  They can be used directly off the Gnulib
-checkout; they don't need to copied first.
+checkout; they don't need to be copied first.
 
 @menu
 * For building shared libraries::

diff --git a/doc/maintainer-makefile.texi b/doc/maintainer-makefile.texi
new file mode 100644 (file)
index 0000000..8dfdf6f
--- /dev/null
+++ b/doc/maintainer-makefile.texi
@@ -0,0 +1,94 @@
+@node maintainer-makefile
+@section maintainer-makefile
+
+@c Copyright (C) 2025 Free Software Foundation, Inc.
+
+@c Permission is granted to copy, distribute and/or modify this document
+@c under the terms of the GNU Free Documentation License, Version 1.3 or
+@c any later version published by the Free Software Foundation; with no
+@c Invariant Sections, no Front-Cover Texts, and no Back-Cover Texts.  A
+@c copy of the license is at <https://www.gnu.org/licenses/fdl-1.3.en.html>.
+
+@cindex making releases
+@mindex maintainer-makefile
+
+Software projects are generally expected to adhere to specific coding
+and maintenance conventions.  GNU projects in particular follow the
+conventions laid out in the GNU Coding Standards and Information for GNU
+Maintainers manuals.  The Gnulib module @code{maintainer-makefile} helps
+automate many of these processes by providing a common framework with
+overridable defaults.
+
+@mindex gnumakefile
+The module includes the files @file{GNUmakefile} (from the
+@code{gnumakefile} module) and @file{maint.mk}, which define several
+convenient targets.  Each target usually comes with a description of its
+workings and the variables that control it.  You can override variables
+and define rules in a file named @file{cfg.mk}, which @file{GNUmakefile}
+will look for.  Some targets may not be relevant to your project, or may
+invoke programs that you do not have installed; you are not required to
+set all of them up.
+
+Below is a summary of the available targets.
+
+@table @code
+@item coverage
+Generate code coverage reports.
+
+@item refresh-gnulib-patches
+@item refresh-po
+Check for updates to external files.
+
+@item release-commit
+@item release
+@item upload
+@item web-manual-update
+Automate the process of making, announcing, and distributing a new
+project release.
+
+@cindex @file{NEWS}, @file{NEWS.md} files
+@mindex announce-gen
+@mindex do-release-commit-and-tag
+These rely on several other modules, including
+@code{do-release-commit-and-tag} and @code{announce-gen}, and expect a
+GNU-like project structure by default.  For example, your project should
+maintain a file @file{NEWS} or @file{NEWS.md} which highlights important
+changes between releases, from new to old.  The section for each release
+is introduced by a heading typically indicating its version, date, and
+type.  Here are some examples:
+
+@example
+* Noteworthy changes in release 1.2 (2025-11-17) [stable]
+# Noteworthy changes in release 1.2 (2025-11-17)
+## Major changes in 1.2.3 (2025-11-17) [beta]
+Changes in 1.2.3 (2025-11-17)
+@end example
+
+The first such heading in the file stands as a placeholder for
+as-yet-unreleased changes.  It typically looks like a template for
+subsequent headings, with details replaced by question marks.  For
+example:
+
+@example
+# Noteworthy changes in release ?.? (????-??-??) [?]
+@end example
+
+Though this file was traditionally named @file{NEWS}, more recent
+versions of Automake and Gnulib also accept @file{NEWS.md}.  If the
+tooling infrastructure you use supports only @file{NEWS} but you would
+prefer to maintain a @file{NEWS.md}, you can try defining the former as
+a symlink to the latter.  In any case, maintaining both names as
+distinct files can be confusing and is therefore discouraged.
+
+@mindex readme-release
+See also the module @code{readme-release}, which outlines a typical GNU
+release process.
+
+@item syntax-check
+Search the project for many suspicious constructs, including unportable
+syntax, stale copyright notices, and misspellings.
+
+@item update-copyright
+@mindex update-copyright
+Update all copyright year lists.
+@end table