-
-
Notifications
You must be signed in to change notification settings - Fork 13.8k
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
rl-23.11: New outline proposal #270257
Comments
Looking at the current "Nixpkgs internals" section, none of these are actually Nixpkgs internal, they all change the interface of Nixpkgs! So I don't think we need such a section.
This sounds odd, table of contents are always at the beginning. If you think it would take up too much space (I don't think it would?), then you can make it smaller by not including the last heading level. Furthermore, I think a section on packages is missing. Nixpkgs' interface is really structured in three incremental level, all of which get a new stable release:
This is mirrored in the Nixpkgs top-level directory structure. |
I disagree with the absence of internal changes, but I don't have time to
expand for now on it. I will try to substantiate this in the next days.
Though I am not attached to the section neither to its title, all that I
care is that we don't do a big mixup of other notable changes that really
doesn't work to convey the information that contributors would ideally read.
Le dim. 26 nov. 2023, 22:20, Silvan Mosberger ***@***.***> a
écrit :
… Looking at the current "Nixpkgs internals" section
<https://github.com/NixOS/nixpkgs/blob/5631ea37394bb38556cbb2b4142cd28ba49ff2d9/nixos/doc/manual/release-notes/rl-2311.section.md#nixpkgs-internals-sec-release-2311-nixpkgs-internals>,
none of these are actually Nixpkgs internal, they all change the interface
of Nixpkgs! So I don't think we need such a section.
The table of contents (TOC) should go last to prevent breaking the normal
reading flow. At least breaking changes should have headings referencing
the software they involve, so it appears in the TOC for quick scanning.
This sounds odd, table of contents are always at the beginning. If you
think it would take up too much space (I don't think it would?), then you
can make it smaller by not including the last heading level.
Furthermore, I think a section on packages is missing. Nixpkgs' interface
is really structured in three incremental level, all of which get a new
stable release:
- nixos
- pkgs
- lib
This is mirrored in the Nixpkgs top-level directory structure.
So I'd try to have a structure in the release notes that also mirrors that.
—
Reply to this email directly, view it on GitHub
<#270257 (comment)>,
or unsubscribe
<https://github.com/notifications/unsubscribe-auth/AACMZRF3SVOZFTSHPX42MBLYGOXDFAVCNFSM6AAAAAA73DOO7KVHI2DSMVQWIX3LMV43OSLTON2WKQ3PNVWWK3TUHMYTQMRWHEYDAMRTGE>
.
You are receiving this because you were mentioned.Message ID:
***@***.***>
|
Not saying there are no internal changes, just that all of the current items in that section are not internal. I guess a truly internal change that would be worthwhile to point out is the |
I think we should still have a section for highlights, maybe they can be summarized in the intro section? |
As far as I know, @alejandrosame thought about the intro section as a highlight section in prose form (id est not bullet point style), yes. |
sounds good to me |
Currently, the outline of previous release notes looks like:
For 23.11, proposed outline:
Rationale
All entries can be split into:
The previous highlights and other notable changes are redundant sections. Check this commit to see how the highlights entries can be moved to either backwards incompatibilities or new services section.
With the introduction of nixpkgs lib release notes with PR 268871, the nixpkgs section of the release notes deserves being highlighted on its own.
The table of contents (TOC) should go last to prevent breaking the normal reading flow. At least breaking changes should have headings referencing the software they involve, so it appears in the TOC for quick scanning.
The intro to the release notes will be prose where the release will be hyped up, and readers will be redirected to the TOC if they wish to quickly scan what's relevant for them.
@riotbib @figsoda @RaitoBezarius @infinisil
The text was updated successfully, but these errors were encountered: