Merge changes I476a2516,I8a274227 into main

* changes:
  doc/hacking: fix internal api docs section to say to enable it
  doc: Add more about the release note generator
This commit is contained in:
jade 2024-06-26 17:34:45 +00:00 committed by Gerrit Code Review
commit 9afb0fe41c
3 changed files with 45 additions and 8 deletions

View file

@ -3,6 +3,10 @@
# #
# It's used for crediting people accurately in release notes. The release notes # 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. # 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: 9999years:
display_name: wiggles display_name: wiggles
forgejo: rbt forgejo: rbt

View file

@ -282,9 +282,8 @@ Regular markdown files used for the manual have a base path of their own and the
## API documentation ## API documentation
Doxygen API documentation is [available Doxygen API documentation will be available online [in the future](https://git.lix.systems/lix-project/lix/issues/422).
online](https://hydra.nixos.org/job/nix/master/internal-api-docs/latest/download-by-type/doc/internal-api-docs). You You can also build and view it yourself:
can also build and view it yourself:
```console ```console
# nix build .#hydraJobs.internal-api-docs # nix build .#hydraJobs.internal-api-docs
@ -294,6 +293,7 @@ can also build and view it yourself:
or inside a `nix develop` shell by running: or inside a `nix develop` shell by running:
```bash ```bash
$ meson configure build -Dinternal-api-docs=enabled
$ meson compile -C build internal-api-docs $ meson compile -C build internal-api-docs
$ xdg-open ./outputs/doc/share/doc/nix/internal-api/html/index.html $ xdg-open ./outputs/doc/share/doc/nix/internal-api/html/index.html
``` ```
@ -320,18 +320,24 @@ User-visible changes should come with a release note.
### Add an entry ### 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 synopsis: Basically a title
# 1234 or gh#1234 will refer to CppNix GitHub, fj#1234 will refer to a Lix forgejo issue. # 1234 or gh#1234 will refer to CppNix GitHub, fj#1234 will refer to a Lix forgejo issue.
issues: [1234, fj#1234] 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 prs: 1238
# List of Lix Gerrit changelist numbers; if there is an associated Lix GitHub # List of Lix Gerrit changelist numbers.
# PR, just put in the Gerrit CL number. # If there is an associated Lix GitHub PR, just put in the Gerrit CL number.
cls: [123] 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. 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 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 ### Build process
Releases have a precomputed `rl-MAJOR.MINOR.md`, and no `rl-next.md`. Releases have a precomputed `rl-MAJOR.MINOR.md`, and no `rl-next.md`.

View file

@ -20,6 +20,8 @@ SIGNIFICANCECES = {
# This is just hardcoded for better validation. If you think there should be # This is just hardcoded for better validation. If you think there should be
# more of them, feel free to add more. # more of them, feel free to add more.
#
# Please update doc/manual/src/contributing/hacking.md if you do. Thanks~
CATEGORIES = [ CATEGORIES = [
'Breaking Changes', 'Breaking Changes',
'Features', 'Features',