[PATCH] D123957: Update the developer policy to mention release notes

Tue Apr 19 11:00:53 PDT 2022

aaron.ballman added a comment.

In D123957#3459557 <https://reviews.llvm.org/D123957#3459557>, @lattner wrote:

> This is awesome, I agree completely we should curate release notes better.  That said, I think this should make it more clear that there is a "difference in kind" between user-facing tools like clang/lldb etc and other libraries in LLVM.  We don't want release note burden (or noise) for every little thing going into the optimizer or codegen.  Do you think it would make sense to point out that this is about user-facing tools?

Oh! I see now where the disconnect was, thanks! That's a good point about user-facing vs not. I'll try to clarify.

In D123957#3459561 <https://reviews.llvm.org/D123957#3459561>, @lattner wrote:

> Also, when this lands, we should post on the forum about it.  Every change to the developer policy warrants broader visibility than just a phab discussion IMO.

Heh, I linked to the phab patch from the RFC but forgot to link to the RFC from the phab patch. Sorry about that! You can find the RFC discussion here: https://discourse.llvm.org/t/rfc-update-developer-policy-on-release-notes/

================
Comment at: llvm/docs/DeveloperPolicy.rst:195
+* Adding, removing, or regrouping a diagnostic.
+* Fixing a bug (please link to the issue fixed in the bug database).
+* Adding or removing an optimization.
----------------
lattner wrote:
> aaron.ballman wrote:
> > nikic wrote:
> > > I disagree with this point. Bug fixes should not make it into the release notes as a matter of course -- there may be specific high-impact bug fixes that may be worth mentioning, but bug fixes should not be included in the release notes as a matter of policy.
> > > 
> > > I agree that release notes for Clang/LLVM are currently insufficient, but we should also be careful not to over-compensate in the other direction, but including too much irrelevant noise.
> > > I disagree with this point. Bug fixes should not make it into the release notes as a matter of course -- there may be specific high-impact bug fixes that may be worth mentioning, but bug fixes should not be included in the release notes as a matter of policy.
> > 
> > I disagree (quite strongly) with this and would point out that users have explicitly requested this information be included: https://discourse.llvm.org/t/rfc-update-developer-policy-on-release-notes/61856/3
> > 
> > > I agree that release notes for Clang/LLVM are currently insufficient, but we should also be careful not to over-compensate in the other direction, but including too much irrelevant noise.
> > 
> > Bug fixes are generally far from irrelevant, but I agree that reviewer and author discretion is advised (as with any release note). For example, if you introduce a bug in version N and fix the bug in version N, there's no need for a release note in that situation because there's no user-facing change as far as users care about. But I don't want to try to spell that out in precise detail because there will always be edge cases.
> I agree with both of you - listing every bug report would be too noisy and pretty irrelevant for most users, but there are high impact ones that are important and valuable to list.  How about wording this bullet something like:
> 
> * Fixing high impact bugs, e.g. ones that get discussed on hackernews or comparable forums (please link to the issue fixed in the bug database).
Thanks for clarifying where I was misunderstanding before. I agree there needs to be a change to my wording, but I'd prefer if we went with something more like:

* Fixing a bug that potentially has significant user-facing impact (please link to the issue fixed in the bug database).

(I mostly want to avoid making it sound like the bug has to be a stop-the-world bug in order to warrant a release note. Functionally, I think fixing a bug in Clang should almost always have a release note, but the same may not be true for fixing a bug in LLVM where the difference in behavior may not be particularly observable to users.)

Would this address your concerns @nikic?

================
Comment at: llvm/docs/DeveloperPolicy.rst:196
+* Fixing a bug (please link to the issue fixed in the bug database).
+* Adding or removing an optimization.
+* Modifying a C stable API.
----------------
lattner wrote:
> This is also too broad IMO, we don't want every new instcombine listed.  I'd recommend making this more user-centric, e.g. "Adding or removing optimizations that have widespread impact or enables new programming paradigms"
+1, good suggestion!

CHANGES SINCE LAST ACTION
  https://reviews.llvm.org/D123957/new/

https://reviews.llvm.org/D123957