Change of policy on release notes appears to be undocumented

[hvdijk]

In https://reviews.llvm.org/D122663, @erichkeane writes:

Our most recent direction is to document any non-NFC patches in the release notes if at all sensible [...]

This is a sensible policy and one that I have no issue with. However, it is not one that has been used in the past and I cannot find any documentation to support it. The only documentation on release notes that I can find is at https://llvm.org/docs/DeveloperPolicy.html, which only states:

Documentation: Any changes to the C API are required to be documented in the release notes so that it’s clear to external users who do not follow the project how the C API is changing and evolving.

An explicit statement that all changes to X are required to be documented in the release notes implies that changes not to X are not generally required to be documented in the release notes except in special cases. I would expect a change to policy to be accompanied by an update to that document, or alternatively to https://llvm.org/docs/CodingStandards.html.

[erichkeane]

Attn: @AaronBallman .

[AaronBallman]

However, it is not one that has been used in the past

We've always requested people write release notes (generally at the end of a release cycle) but some of the more active reviewers are getting more consistent about asking recently due to significant user feedback about the poor quality of our release notes.

An explicit statement that all changes to X are required to be documented in the release notes implies that changes not to X are not generally required to be documented in the release notes except in special cases.

I can see how you'd read it that way, but it's definitely not intended as such. That would make the release notes pretty... weird... given that they come prepopulated with a ton of headings that having nothing to do with the C APIs. :-)

I would expect a change to policy to be accompanied by an update to that document, or alternatively to https://llvm.org/docs/CodingStandards.html.

I think it's totally reasonable to request that we document this. I can look into fixing up the docs to make it more clear, thanks for pointing it out!

[AaronBallman]

FWIW, I've posted an RFC at https://discourse.llvm.org/t/rfc-update-developer-policy-on-release-notes and I've posted a review at https://reviews.llvm.org/D123957.

[hvdijk]

Thank you for the quick work, FWIW I'm quite happy with the wording you're proposing.

[DavidSpickett]

We have a section on release notes today (https://llvm.org/docs/DeveloperPolicy.html#release-notes), closing this as done.