llvm dev - Apr 2020 - What is the process for release notes for LLVM

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

> On 29 Apr 2020, at 2:05 pm, Robinson, Paul via llvm-dev <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> 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>
> 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
> _______________________________________________
> LLVM Developers mailing list
> llvm-dev at lists.llvm.org
> https://lists.llvm.org/cgi-bin/mailman/listinfo/llvm-dev
--
Sam Elliott
Software Team Lead
Senior Software Developer - LLVM and OpenTitan
lowRISC CIC

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> 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
>
>
> > On 29 Apr 2020, at 2:05 pm, Robinson, Paul via llvm-dev <
> 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> 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>
> > 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
> > _______________________________________________
> > LLVM Developers mailing list
> > llvm-dev at lists.llvm.org
> > https://lists.llvm.org/cgi-bin/mailman/listinfo/llvm-dev
>
> --
> Sam Elliott
> Software Team Lead
> Senior Software Developer - LLVM and OpenTitan
> lowRISC CIC
>
>
-------------- next part --------------
An HTML attachment was scrubbed...
URL:
<http://lists.llvm.org/pipermail/llvm-dev/attachments/20200430/b09b9ad5/attachment.html>

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.

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.

On Thu, Apr 30, 2020 at 1:57 AM James Henderson via llvm-dev <
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>
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
>>
>>
>> > On 29 Apr 2020, at 2:05 pm, Robinson, Paul via llvm-dev <
>> 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> 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>
>> > 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
>> > _______________________________________________
>> > LLVM Developers mailing list
>> > llvm-dev at lists.llvm.org
>> > https://lists.llvm.org/cgi-bin/mailman/listinfo/llvm-dev
>>
>> --
>> Sam Elliott
>> Software Team Lead
>> Senior Software Developer - LLVM and OpenTitan
>> lowRISC CIC
>>
>> _______________________________________________
> LLVM Developers mailing list
> llvm-dev at lists.llvm.org
> https://lists.llvm.org/cgi-bin/mailman/listinfo/llvm-dev
>
-------------- next part --------------
An HTML attachment was scrubbed...
URL:
<http://lists.llvm.org/pipermail/llvm-dev/attachments/20200430/6f740692/attachment.html>