[llvm-dev] What is the process for release notes for LLVM

Thu Apr 30 12:01:11 PDT 2020

On Thu, Apr 30, 2020 at 11:57 AM Fangrui Song <maskray at google.com> wrote:

> On 2020-04-30, Robinson, Paul via llvm-dev wrote:
> >For the tools (which I know is mostly what James works on) I’d say new
> command-line options are worth release-noting as a way to advertise their
> existence.
> >
> >From: llvm-dev <llvm-dev-bounces at lists.llvm.org> On Behalf Of David
> Blaikie via llvm-dev
> >Sent: Thursday, April 30, 2020 11:47 AM
> >To: James Henderson <jh7370.2008 at my.bristol.ac.uk>
> >Cc: LLVM Developers Mailing List <llvm-dev at lists.llvm.org>
> >Subject: Re: [llvm-dev] What is the process for release notes for LLVM
> >
> >Eh - I'd say "Big" new features (hey, LLVM supports DWARFv5, or Split
> DWARF, or DWARF type units, or DWARF compression (though I don't think I
> wrote any release notes for several of those features that I implemented)).
> >
> >I wouldn't bother release noting changes in output format for tools we
> don't consider to have stable output, or changes in robustness/better error
> handling/reporting as a broad thing - if there's some specific goal reached
> (llvm-dwarfdump is now X days fuzzer-clean & provides more informative
> error messages about failures) that might be worth noting, imho.
>
> Maybe a brief sentence like `Diagnostics messages have improved` is
> sufficient.
> I did this for
> https://releases.llvm.org/9.0.0/tools/lld/docs/ReleaseNotes.html#elf-improvements
> (Thanks to Peter Smith who revised my wording)
>
> >FileCheck/lit/yaml2obj - if you like.
> >
> >I suspect "too many release notes" is probably a problem that would be
> novel/worth having, so if you want to write more, perhaps do so I & if it
> seems like too many, we can cut back/retune.
>
> Looking at
> https://releases.llvm.org/10.0.0/docs/ReleaseNotes.html
> https://releases.llvm.org/10.0.0/tools/clang/docs/ReleaseNotes.html
> most items don't include a link to Dxxxxx.
> A user needs some log grepping to find the particular differential
> revisions.
>
> Where possible, I hope we include a link.  I added Dxxxx links for lld
> 10.0.0 ELF items
> https://releases.llvm.org/10.0.0/tools/lld/docs/ReleaseNotes.html#elf-improvements
> (In my opinion Dxxxxx is better than rGxxxxxx because Dxxxxx includes
>   discussions and can save an interested user a hyperlink click.)
>

FWIW, I'd tend to prefer the source control reference - it's
authoritative/all commits have one/etc.

& ideally if we did a better job of committing release notes with the
actual change that they're noting - then the commit log for the changelog
will help identify the relevant commit for more context on a decision,
details on how it's implemented, etc.

>
> >On Thu, Apr 30, 2020 at 1:57 AM James Henderson via llvm-dev <
> llvm-dev at lists.llvm.org<mailto:llvm-dev at lists.llvm.org>> wrote:
> >Okay, thanks both, that's useful to know/think about.
> >
> >I guess it doesn't really answer my question of "when is a release note
> appropriate"? I've seen in different software release notes that range from
> one per change, even if not user-facing, all the way to almost none at all,
> and I'm not sure where to draw the balance (aside from if the release
> manager wants one, add it). For example, should we add release notes if the
> error diagnostics from a tool change (text
> updates/quantity/warnings->errors or vice versa/etc)? Should all new
> options have an accompanying release note? What about format changes to
> llvm binutils output? And which tools should we be producing release notes
> for? Should they exist for FileCheck, lit or yaml2obj even though these are
> primarily intended for our internal testing?
> >
> >On Wed, 29 Apr 2020 at 15:49, Sam Elliott <selliott at lowrisc.org<mailto:
> selliott at lowrisc.org>> wrote:
> >This approximately follows my understanding and expectation.
> >
> >I think that, if you have commit access, commits to improve release notes
> fall under the contribution guidelines for documentation and therefore do
> not require a full Phabricator review.
> >
> >I know Alex Bradbury tries to coordinate the RISC-V backend-related
> release notes based on the backend changes since the last release, and this
> seems to work well (in some cases soliciting notes, in some cases just
> writing up what others had done). It does seem that role should not just
> fall on the shoulders of a backend or component owner, though.
> >
> >I would agree that it could be easier to update release notes in patches
> that make the changes to keep everything together, although I'm not sure
> how this affects backporting patches (solving merge conflicts in release
> notes seems like it could be rather infuriating if it happened a lot).
> >
> >Sam
>
> I have seen Android and FreeBSD folks back porting specific commits.
> I think it might make their life easier if we update release notes
> separately.
>
> >
> >> On 29 Apr 2020, at 2:05 pm, Robinson, Paul via llvm-dev <
> llvm-dev at lists.llvm.org<mailto:llvm-dev at lists.llvm.org>> wrote:
> >>
> >> The way things work in practice is, when it’s time for a release, the
> release manager makes a general plea for people to write release notes.
> This might include pleas to individuals whom the release manager has
> noticed made a note-worthy change; I seem to remember getting one such
> email once upon a time.
> >>
> >> Asking for a release note as part of the review would be a new thing,
> but IMO brilliant.
> >> --paulr
> >> From: llvm-dev <llvm-dev-bounces at lists.llvm.org<mailto:
> llvm-dev-bounces at lists.llvm.org>> On Behalf Of James Henderson via
> llvm-dev
> >> Sent: Wednesday, April 29, 2020 8:58 AM
> >> To: llvm-dev <llvm-dev at lists.llvm.org<mailto:llvm-dev at lists.llvm.org>>
> >> Subject: [llvm-dev] What is the process for release notes for LLVM
> >>
> >> Hi all,
> >>
> >> I'm aware that LLVM has release notes, but I've never written one
> myself, despite making at times some fairly significant changes to the
> various llvm tools. Is there any documentation in LLVM on when a release
> note is appropriate and how to write one? Should reviewers be asking people
> to write release notes as part of reviews?
> >>
> >> James
>
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.llvm.org/pipermail/llvm-dev/attachments/20200430/96cf11f9/attachment.html>