Fangrui Song via llvm-dev
2020-Apr-30 18:57 UTC
[llvm-dev] What is the process for release notes for LLVM
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.)>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). > >SamI 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
David Blaikie via llvm-dev
2020-Apr-30 19:01 UTC
[llvm-dev] What is the process for release notes for LLVM
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>
James Henderson via llvm-dev
2020-May-01 08:33 UTC
[llvm-dev] What is the process for release notes for LLVM
Great, thanks for all the advice. I'm going to try to start writing release notes as I go/encourage people to do so in the areas I work in then. On the commit versus Phabricator reference, my personal preference is the former, for similar reasons to David Blaikie, but I can be persuaded otherwise. On back-porting, I would have thought that a release note got updated in the same commit as the fix, that would be good? That would mean the release note would make its way into the release note for the given local version of the tree, and would therefore more accurately reflect what was in that particular downstream version of LLVM. On Thu, 30 Apr 2020 at 20:01, David Blaikie <dblaikie at gmail.com> wrote:> > > 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/20200501/b10806a1/attachment-0001.html>