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:
> I experimented with the changes on a branch of libntlm using the > NEWS->NEWS.md symlink approach, and it just worked, so I think I may > have anticipated more trouble than actually occurs. I'm not ready (at > least for some projects) to not have a NEWS file at all because that's > the GNU standard and some tooling breaks without it. Maybe I can find > some niche project and move to a NEWS.md only and see if there is any > breakage. Thanks! I'd be curious to know which tooling that is, e.g. whether it's project-specific automation or something more widespread. >> SGTM. Shall I reply to Richard in the bug-standards subthread[0] with >> something as simple as the following, or would someone else like to? > Please do! Looks okay to me. Thanks, now done: https://lists.gnu.org/r/bug-standards/2025-11/msg00002.html > 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. >>>> What is not yet supported is a generalisation from one NEWS file to an >>>> arbitrary number of them, e.g. for different subsystems in the fashion >>>> of Emacs' etc/{,EGLOT-,ERC-}NEWS files. >>> >>> I don't think we need to consider this. >> >> Then I don't think we need to worry about parallel NEWS and NEWS.md >> until someone justifies such support. > > That would imply the recommendation is to rename NEWS to NEWS.md, > doesn't it? Does it? Is there anything wrong with sticking with NEWS? [ I was replying to your question about projects that may have distinct NEWS and NEWS.md files. ] > I doubt that all projects are ready to give up the NEWS > name, and I think a slow migration by using a symlink is a reasonable > approach to avoid having two files with different content. So maybe > that could be mentioned. Agreed. Thanks, -- Basil
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..54608643a7 --- /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 gnumakefile +@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 GNU Maintainer +Information manuals. The Gnulib module @code{maintainer-makefile} helps +automate many of these processes by providing a common framework with +overridable defaults. + +The module includes the files @file{GNUmakefile} (from the +@code{gnumakefile} module) and @file{maint.mk}, which define several +convenient targets. Each one 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
