From e537678f1ecfa3c1a145977e752ab826b10386ca Mon Sep 17 00:00:00 2001 From: Jade Lovelace Date: Tue, 25 Jun 2024 21:22:37 -0700 Subject: [PATCH] doc: Add more about the release note generator Change-Id: I8a274227cb1b05d442d3f644603dd2844ecc9d05 --- doc/manual/change-authors.yml | 4 +++ doc/manual/src/contributing/hacking.md | 41 ++++++++++++++++++++++---- maintainers/build-release-notes.py | 2 ++ 3 files changed, 42 insertions(+), 5 deletions(-) diff --git a/doc/manual/change-authors.yml b/doc/manual/change-authors.yml index 5a7b8117e..5894ce821 100644 --- a/doc/manual/change-authors.yml +++ b/doc/manual/change-authors.yml @@ -3,6 +3,10 @@ # # It's used for crediting people accurately in release notes. The release notes # script will link to forgejo, then to GitHub if forgejo is not present. +# +# When adding someone from outside the Lix project, you generally want to simply link their GitHub profile without adding a display name unless they are well-known in the community by that display name. +# +# See doc/manual/src/contributing/hacking.md for more documentation on this file's format and typical usage. 9999years: display_name: wiggles forgejo: rbt diff --git a/doc/manual/src/contributing/hacking.md b/doc/manual/src/contributing/hacking.md index cd4f6d5d5..3fe6022d4 100644 --- a/doc/manual/src/contributing/hacking.md +++ b/doc/manual/src/contributing/hacking.md @@ -320,18 +320,24 @@ User-visible changes should come with a release note. ### Add an entry -Here's what a complete entry looks like. The file name is not incorporated in the document. +Here's what a complete entry looks like. +The file name is not incorporated in the final document, and is generally a super brief summary of the change synopsis. -``` +```markdown --- synopsis: Basically a title # 1234 or gh#1234 will refer to CppNix GitHub, fj#1234 will refer to a Lix forgejo issue. issues: [1234, fj#1234] -# Use this *only* if there is a CppNix pull request associated with this change +# Use this *only* if there is a CppNix pull request associated with this change. prs: 1238 -# List of Lix Gerrit changelist numbers; if there is an associated Lix GitHub -# PR, just put in the Gerrit CL number. +# List of Lix Gerrit changelist numbers. +# If there is an associated Lix GitHub PR, just put in the Gerrit CL number. cls: [123] +# Heading that this release note will appear under. +category: Breaking Changes +# Add a credit mention in the bottom of the release note. +# your-name is used as a key into doc/manual/change-authors.yml for metadata +credits: [your-name] --- Here's one or more paragraphs that describe the change. @@ -346,6 +352,31 @@ Significant changes should add the following header, which moves them to the top significance: significant ``` +The following categories of release notes are supported (see `maintainers/build-release-notes.py`): +- Breaking Changes +- Features +- Improvements +- Fixes +- Packaging +- Development +- Miscellany + +The `credits` field, if present, gives credit to the author of the patch in the release notes with a message like "Many thanks to (your-name) for this" and linking to GitHub or Forgejo profiles if listed. + +If you are forward-porting a change from CppNix, please credit the original author, and optionally credit yourself. +When adding credits metadata for people external to the project and deciding whether to put in a `display_name`, consider what they are generally known as in the community; even if you know their full name (e.g. from their GitHub profile), we suggest only adding it as a display name if that is what they go by in the community. +There are multiple reasons we follow this practice, but it boils down to privacy and consent: we would rather not capture full names that are not widely used in the community without the consent of the parties involved, even if they are publicly available. +As of this writing, the entries with full names as `display_name` are either members of the CppNix team or people who added them themselves. + +The names specified in `credits` are used as keys to look up the authorship info in `doc/manual/change-authors.yml`. +The only mandatory part is that every key appearing in `credits` has an entry present in `change-authors.yml`. +All of the following properties are optional; you can specify `{}` as the metadata if you want a simple non-hyperlinked mention. +The following properties are supported: + +- `display_name`: display name used in place of the key when showing names, if present. +- `forgejo`: Forgejo username. The name in the release notes will be a link to this, if present. +- `github`: GitHub username, used if `forgejo` is not set, again making a link. + ### Build process Releases have a precomputed `rl-MAJOR.MINOR.md`, and no `rl-next.md`. diff --git a/maintainers/build-release-notes.py b/maintainers/build-release-notes.py index f91d68cef..97985b970 100644 --- a/maintainers/build-release-notes.py +++ b/maintainers/build-release-notes.py @@ -20,6 +20,8 @@ SIGNIFICANCECES = { # This is just hardcoded for better validation. If you think there should be # more of them, feel free to add more. +# +# Please update doc/manual/src/contributing/hacking.md if you do. Thanks~ CATEGORIES = [ 'Breaking Changes', 'Features',