"Basil L. Contovounesios" <[email protected]> writes: > Basil L. Contovounesios [2025-12-04 13:34 +0100] wrote: >> My papers should be on file now, so I reattach the diff as a patch. > > Ping. > Is there interest in documenting maintainer-makefile along these lines?
Committed now. I read through it and was surprised we didn't have this documented already. Thank you! Btw, I recently read https://www.karl-voit.at/2025/08/17/Markdown-disaster/ and realized that gitlab/github had reasonable support for orgdown markup, so maybe adding support for *.org files too would be useful? Btw, I have migrated InetUtils and Libtasn1 to use NEWS.md files, and done releases of these projects, and things work fine, although there is one problem: I still have a NEWS -> NEWS.md symlink in the git repository, or there are automake warnings. This leads to two copies of the NEWS file in the tarball since automake somehow replaces symlinks with real content, so it is shipped both as NEWS and NEWS.md. Most probably this compresses really well, so I don't think it is a serious problem, but it is not nice. I don't know what the best way to resolve this is. I think I would prefer just giving up on the NEWS filename and just have a NEWS.md file in the git repository, and only have a NEWS.md file in the tarball too. But autoconf/automake tooling doesn't like this, and I don't know how to resolve that in a backwards compatible way. Thoughts? /Simon >> 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 > > Thanks,
signature.asc
Description: PGP signature
