Basil L. Contovounesios [2025-11-17 16:01 +0100] wrote: > Simon Josefsson [2025-11-17 11:59 +0100] wrote: >> "Basil L. Contovounesios" <[email protected]> writes: >>> Simon Josefsson [2025-11-16 17:24 +0100] wrote: >>>> "Basil L. Contovounesios" <[email protected]> writes: > >> Did you assign copyright for gnulib? Sorry we should have asked this >> earlier to get the ball started on that. > > I only sent in the CA request form on 2025-11-12, so it may take a bit > longer to hear back from the clerk. I can ping this thread again when > the process is complete if that's helpful. > >>>> My comments are more about how we intend things to be, and if we can or >>>> need to modify documentation. I think we 1) should modify GNU standards >>>> to say permit NEWS.md, and 2) could improve the gnulib manual to >>>> describe the assumptions our tooling make about handle NEWS(.md) files, >>>> which implicitly becomes a recommended approach. >>> >>> Where do you suggest adding the latter? >>> - (gnulib) Miscellaneous Notes >>> - (gnulib) Release Management Files >>> - ... >>> >>> I would have included it with the documentation for readme-release or >>> maintainer-makefile, but those are documented inline, not in the >>> manual. >> >> I think either place is fine, the texinfo manual better than inline in >> scripts, as a starting point to get this documented. > > Actually, perhaps "(gnulib) Build Infrastructure Modules" is more > suitable. I wasn't sure how to bring up the topic of NEWS formats > without either introducing maintainer-makefile, or repeating parts of > standards.texi or maintain.texi, so I went with the former. > > I attach an initial draft (at the very least it's missing some xrefs). > WDYT? Suggestions more than welcome.
My papers should be on file now, so I reattach the diff as a patch. Thanks, -- Basil
>From 2475f33567b3ea9ff52ee089d872b83959345157 Mon Sep 17 00:00:00 2001 From: "Basil L. Contovounesios" <[email protected]> Date: Mon, 17 Nov 2025 18:33:52 +0100 Subject: [PATCH] doc: Add maintainer-makefile section to manual. Suggested by Simon Josefsson <[email protected]> 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. --- ChangeLog | 10 ++++ doc/gnulib.texi | 7 ++- doc/maintainer-makefile.texi | 94 ++++++++++++++++++++++++++++++++++++ 3 files changed, 109 insertions(+), 2 deletions(-) create mode 100644 doc/maintainer-makefile.texi diff --git a/ChangeLog b/ChangeLog index a0b7257a1f..b74eabc233 100644 --- a/ChangeLog +++ b/ChangeLog @@ -1,3 +1,13 @@ +2025-12-04 Basil L. Contovounesios <[email protected]> + + doc: Add maintainer-makefile section to manual. + Suggested by Simon Josefsson <[email protected]> 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. + 2025-12-04 Bruno Haible <[email protected]> Rename some local variables. diff --git a/doc/gnulib.texi b/doc/gnulib.texi index 53da100824..2674f38c29 100644 --- a/doc/gnulib.texi +++ b/doc/gnulib.texi @@ -8227,6 +8227,7 @@ Build Infrastructure Modules * Package version management:: * VCS To ChangeLog:: * gitlog-to-changelog:: +* maintainer-makefile:: @end menu @include havelib.texi @@ -8249,6 +8250,8 @@ Build Infrastructure Modules @include gitlog-to-changelog.texi +@include maintainer-makefile.texi + @node Build Infrastructure Files @chapter Build Infrastructure Files @@ -8473,9 +8476,9 @@ For running tests @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 index 0000000000..8dfdf6f85c --- /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 -- 2.51.0
