x/build/cmd/relnote: improve experience for documenting new standard library packages

[dmitshur]

The cmd/relnote test requires that all new APIs have a corresponding entry in doc/next/*-stdlib/*-minor. This works as intended for most APIs, but some new APIs are entirely new packages. Those are not considered "minor" changes, and get their own heading.

The current approach for new packages is to include a file in *-minor/nnn.md anyway, but make its content just a comment like "<!-- This is a new package; covered in 6-stdlib/5-sha3.md. -->".

This causes some friction down the road, as relnote generate ends up creating empty headings like these:

https://cs.opensource.google/go/x/website/+/master:_content/doc/go1.24.md;l=271-277;drc=4ccfb99db16b1419ac640fb08dd654053bd819ee

Those need to eventually be removed.

This is a tracking issue to improve this edge case. A simple fix is to make relnote generate detect when a fragment contains nothing but a comment, and in such cases avoid creating a heading. A more involved change would be to make the cmd/relnote test recognize when a new package is documented in *-stdlib and not require the file with a comment to be added in the first place, if that can be done without risking forgetting to document such changes.

CC @golang/release.

[gabyhelp]

Related Issues

• x/build/cmd/relnote: document RELNOTE marker rules #37752 (closed)

_{(Emoji vote if this was helpful or unhelpful; more detailed feedback welcome in this discussion.)}