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

Fri May 1 08:29:24 PDT 2020

On Fri, May 1, 2020 at 1:33 AM James Henderson <jh7370.2008 at my.bristol.ac.uk>
wrote:

> 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.
>

I think the only problem then would be that the release note would end up
both in the impending release /and/ the next release? (but I forget exactly
how the release notes document is structured (yeah, the document gets
emptied after the branch - so that new notes relate only to the next
release)) - so I think if a patch including release notes got cherry
picked, you'd want to then commit a follow-up on mainline to delete that
release note, since it's now going to appear in the impending release and
shouldn't also appear in the release after that.

>
> 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/b314c536/attachment.html>