rl-23.11: New outline proposal

[alejandrosame]

Currently, the outline of previous release notes looks like:

- Highlights
- New services
- Backwards incompatibilities
- Other notable changes
- Nixpkgs internals

For 23.11, proposed outline:

- Intro
- NIXOS
    + breaking changes
        * A
        * B
        * ...
    + new services 
- NIXPKGS
    + lib
    + internals
- RELEASE TOC

Rationale

All entries can be split into:

• breaking changes: those that require the user to take action or change default value.
• new services: the user might be interested in using some new functionality.
• internals: non visible changes, possibly refactors that at least aim to maintain compatibility.

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

[infinisil]

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.

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.

[RaitoBezarius]

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: ***@***.***>

[infinisil]

I disagree with the absence of internal changes

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 pkgs/by-name introduction, which might invite more people to contribute, or the contributor docs cleanup. At least these are the ones I know about :)

[figsoda]

I think we should still have a section for highlights, maybe they can be summarized in the intro section?

[riotbib]

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.

[figsoda]

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