You are viewing a plain text version of this content. The canonical link for it is here.
Posted to dev@beam.apache.org by Ahmet Altay <al...@google.com> on 2020/02/01 01:09:39 UTC
Re: [DISCUSSION] Improve release notes by adding a change list file
Thank you for the quick responses. I sent out
https://github.com/apache/beam/pull/10743 to make this change. Please
provide feedback or directly edit the PR.
On Fri, Jan 31, 2020 at 3:58 PM Robert Bradshaw <ro...@google.com> wrote:
> Yes, yes, yes! This is the one model of release notes that I've
> actually seen work well at scale.
>
>
> https://lists.apache.org/thread.html/41e03ace17dbcccf7e267ba6d538736b2a99a8e73e7fb45702766b17%40%3Cdev.beam.apache.org%3E
>
> Let's make it happen.
>
> On Fri, Jan 31, 2020 at 3:47 PM Robert Burke <ro...@frantil.com> wrote:
> >
> > I like this suggestion, Jira titles and commit summaries don't
> necessarily reflect the user impact for a given change (or set of changes).
> Being able to see the Forest instead of the trees.
> >
> > On Fri, Jan 31, 2020, 3:37 PM Kenneth Knowles <ke...@apache.org> wrote:
> >>
> >> +1
> >>
> >> This is a great idea. Hope it can lead to higher-value view of relevant
> changes.
> >>
> >> I like it being in the root of the repo, so it lives next to the code.
> >>
> >> Since the website is also markdown, it could be copied over directly at
> release time, so it can be browsed there, too.
> >>
> >> Kenn
> >>
> >> On Fri, Jan 31, 2020 at 3:16 PM Ahmet Altay <al...@google.com> wrote:
> >>>
> >>> Hi all,
> >>>
> >>> We currently have two major ways to communicate changes in a release:
> >>> - A blog post, to highlight major changes in the release. (Example for
> 2.17: [1])
> >>> - JIRA release notes pages listing all issues tagged for a specific
> release. (Example for 2.17 [2]).
> >>>
> >>> There are a few issues with this process:
> >>> - It is difficult for the release manager to know what is important,
> what is a breaking change, what is dependency change etc. For example,
> there were more than 150 Jira issues tagged for 2.17 release.
> >>> - Release blog has many items, and does not necessarily communicate
> important changes. It is difficult for users to discover major changes
> short of going through a large list.
> >>> - People involved in authoring or reviewing a PRs usually have the
> most context about the change, and they are not necessarily involved in the
> release process to provide this additional information.
> >>>
> >>> Would it be helpful if we maintain a simple change list file and
> update it as part of the PRs with noteworthy changes? Release managers
> could use this information as is in their blog posts (or link to it). Users
> will have a single place to find highlights from various versions.
> >>>
> >>> Concretely, I am proposing:
> >>> - Adding a CHANGES file to the root of the repository. (Name could be
> anything, TFX uses RELEASE.md in their repo. [3])
> >>> - Ask PR authors to update this file as part of their PR whenever it
> makes sense
> >>> - Reference this file during the release process, and a new section
> for the next release after each release.
> >>>
> >>> Ahmet
> >>>
> >>> [1] https://beam.apache.org/blog/2020/01/06/beam-2.17.0.html
> >>> [2]
> https://issues.apache.org/jira/secure/ReleaseNote.jspa?version=12345970&projectId=12319527
> >>> [3] https://github.com/tensorflow/tfx/blob/master/RELEASE.md
>
Re: [DISCUSSION] Improve release notes by adding a change list file
Posted by Ahmet Altay <al...@google.com>.
There are a few approvals on the PR and no objections in this thread. I
will merge the PR.
Thank you all for the feedback. And please remind PR authors to update this
file to make it a reality. Hopefully this will make releases a tiny bit
easier and provide better information for users.
Ahmet
On Mon, Feb 3, 2020 at 5:15 PM Ahmet Altay <al...@google.com> wrote:
> Done, updated the PR template checklist as well.
>
> On Mon, Feb 3, 2020 at 5:05 PM Udi Meiri <eh...@google.com> wrote:
>
>> +1 to add this to the checklist
>>
>> On Mon, Feb 3, 2020 at 4:57 PM Robert Bradshaw <ro...@google.com>
>> wrote:
>>
>>> On Mon, Feb 3, 2020 at 4:49 PM Ahmet Altay <al...@google.com> wrote:
>>> >
>>> > On Mon, Feb 3, 2020 at 2:09 PM Robert Bradshaw <ro...@google.com>
>>> wrote:
>>> >>
>>> >> I would suggest we start with the simpler single file. If merge
>>> >> conflicts become an issue, we could look at other options, but I think
>>> >> it's worth keeping in mind that what we're trying to produce here is a
>>> >> single, higher-level, cohesive summary of the release rather than a
>>> >> 1:1 listing of commits, pull request, or jira entries (which we can
>>> >> link to). While new features often merit their own bullet points, this
>>> >> will allow for entries such as "Several improvements to portability
>>> >> including ..."
>>> >
>>> > I agree. If there are no objections I will go ahead with the PR I
>>> proposed. It adds a single change log file to begin with.
>>> >
>>> > We would need all committers to help after that by asking PR authors
>>> to update this file whenever it makes sense.
>>>
>>> Yes. Should we add it to the PR template checklist?
>>>
>>> >> On Mon, Feb 3, 2020 at 1:55 PM Ahmet Altay <al...@google.com> wrote:
>>> >> >
>>> >> >
>>> >> >
>>> >> > On Sat, Feb 1, 2020 at 9:22 AM Chad Dombrova <ch...@gmail.com>
>>> wrote:
>>> >> >>
>>> >> >> In case it's of any use, there's a tool called towncrier[1] to
>>> help compile changelog fragments and compile them at time of delivery.
>>> >> >
>>> >> >
>>> >> > I would prefer not to have the complexity of multiple files and an
>>> added tool to the release process. I do not have a strong opinion though.
>>> If others prefer we can switch to this tool. One nice benefit of this tool
>>> would be to avoid merge conflicts if many different PRs edit the change log
>>> file all at the same time in a conflicting way.
>>> >> >
>>> >> >>
>>> >> >>
>>> >> >> I came across this when working on the python-attrs[2] project,
>>> which has some good documentation for contributors on how to use it:
>>> https://www.attrs.org/en/stable/contributing.html#changelog
>>> >> >>
>>> >> >>
>>> >> >> [1] https://github.com/hawkowl/towncrier
>>> >> >> [2] https://github.com/python-attrs/attrs
>>> >> >>
>>> >> >>
>>> >> >> On Fri, Jan 31, 2020 at 5:09 PM Ahmet Altay <al...@google.com>
>>> wrote:
>>> >> >>>
>>> >> >>> Thank you for the quick responses. I sent out
>>> https://github.com/apache/beam/pull/10743 to make this change. Please
>>> provide feedback or directly edit the PR.
>>> >> >>>
>>> >> >>>
>>> >> >>> On Fri, Jan 31, 2020 at 3:58 PM Robert Bradshaw <
>>> robertwb@google.com> wrote:
>>> >> >>>>
>>> >> >>>> Yes, yes, yes! This is the one model of release notes that I've
>>> >> >>>> actually seen work well at scale.
>>> >> >>>>
>>> >> >>>>
>>> https://lists.apache.org/thread.html/41e03ace17dbcccf7e267ba6d538736b2a99a8e73e7fb45702766b17%40%3Cdev.beam.apache.org%3E
>>> >> >>>>
>>> >> >>>> Let's make it happen.
>>> >> >>>>
>>> >> >>>> On Fri, Jan 31, 2020 at 3:47 PM Robert Burke <ro...@frantil.com>
>>> wrote:
>>> >> >>>> >
>>> >> >>>> > I like this suggestion, Jira titles and commit summaries don't
>>> necessarily reflect the user impact for a given change (or set of changes).
>>> Being able to see the Forest instead of the trees.
>>> >> >>>> >
>>> >> >>>> > On Fri, Jan 31, 2020, 3:37 PM Kenneth Knowles <ke...@apache.org>
>>> wrote:
>>> >> >>>> >>
>>> >> >>>> >> +1
>>> >> >>>> >>
>>> >> >>>> >> This is a great idea. Hope it can lead to higher-value view
>>> of relevant changes.
>>> >> >>>> >>
>>> >> >>>> >> I like it being in the root of the repo, so it lives next to
>>> the code.
>>> >> >>>> >>
>>> >> >>>> >> Since the website is also markdown, it could be copied over
>>> directly at release time, so it can be browsed there, too.
>>> >> >>>> >>
>>> >> >>>> >> Kenn
>>> >> >>>> >>
>>> >> >>>> >> On Fri, Jan 31, 2020 at 3:16 PM Ahmet Altay <al...@google.com>
>>> wrote:
>>> >> >>>> >>>
>>> >> >>>> >>> Hi all,
>>> >> >>>> >>>
>>> >> >>>> >>> We currently have two major ways to communicate changes in a
>>> release:
>>> >> >>>> >>> - A blog post, to highlight major changes in the release.
>>> (Example for 2.17: [1])
>>> >> >>>> >>> - JIRA release notes pages listing all issues tagged for a
>>> specific release. (Example for 2.17 [2]).
>>> >> >>>> >>>
>>> >> >>>> >>> There are a few issues with this process:
>>> >> >>>> >>> - It is difficult for the release manager to know what is
>>> important, what is a breaking change, what is dependency change etc. For
>>> example, there were more than 150 Jira issues tagged for 2.17 release.
>>> >> >>>> >>> - Release blog has many items, and does not necessarily
>>> communicate important changes. It is difficult for users to discover major
>>> changes short of going through a large list.
>>> >> >>>> >>> - People involved in authoring or reviewing a PRs usually
>>> have the most context about the change, and they are not necessarily
>>> involved in the release process to provide this additional information.
>>> >> >>>> >>>
>>> >> >>>> >>> Would it be helpful if we maintain a simple change list file
>>> and update it as part of the PRs with noteworthy changes? Release managers
>>> could use this information as is in their blog posts (or link to it). Users
>>> will have a single place to find highlights from various versions.
>>> >> >>>> >>>
>>> >> >>>> >>> Concretely, I am proposing:
>>> >> >>>> >>> - Adding a CHANGES file to the root of the repository. (Name
>>> could be anything, TFX uses RELEASE.md in their repo. [3])
>>> >> >>>> >>> - Ask PR authors to update this file as part of their PR
>>> whenever it makes sense
>>> >> >>>> >>> - Reference this file during the release process, and a new
>>> section for the next release after each release.
>>> >> >>>> >>>
>>> >> >>>> >>> Ahmet
>>> >> >>>> >>>
>>> >> >>>> >>> [1] https://beam.apache.org/blog/2020/01/06/beam-2.17.0.html
>>> >> >>>> >>> [2]
>>> https://issues.apache.org/jira/secure/ReleaseNote.jspa?version=12345970&projectId=12319527
>>> >> >>>> >>> [3] https://github.com/tensorflow/tfx/blob/master/RELEASE.md
>>>
>>
Re: [DISCUSSION] Improve release notes by adding a change list file
Posted by Ahmet Altay <al...@google.com>.
Done, updated the PR template checklist as well.
On Mon, Feb 3, 2020 at 5:05 PM Udi Meiri <eh...@google.com> wrote:
> +1 to add this to the checklist
>
> On Mon, Feb 3, 2020 at 4:57 PM Robert Bradshaw <ro...@google.com>
> wrote:
>
>> On Mon, Feb 3, 2020 at 4:49 PM Ahmet Altay <al...@google.com> wrote:
>> >
>> > On Mon, Feb 3, 2020 at 2:09 PM Robert Bradshaw <ro...@google.com>
>> wrote:
>> >>
>> >> I would suggest we start with the simpler single file. If merge
>> >> conflicts become an issue, we could look at other options, but I think
>> >> it's worth keeping in mind that what we're trying to produce here is a
>> >> single, higher-level, cohesive summary of the release rather than a
>> >> 1:1 listing of commits, pull request, or jira entries (which we can
>> >> link to). While new features often merit their own bullet points, this
>> >> will allow for entries such as "Several improvements to portability
>> >> including ..."
>> >
>> > I agree. If there are no objections I will go ahead with the PR I
>> proposed. It adds a single change log file to begin with.
>> >
>> > We would need all committers to help after that by asking PR authors to
>> update this file whenever it makes sense.
>>
>> Yes. Should we add it to the PR template checklist?
>>
>> >> On Mon, Feb 3, 2020 at 1:55 PM Ahmet Altay <al...@google.com> wrote:
>> >> >
>> >> >
>> >> >
>> >> > On Sat, Feb 1, 2020 at 9:22 AM Chad Dombrova <ch...@gmail.com>
>> wrote:
>> >> >>
>> >> >> In case it's of any use, there's a tool called towncrier[1] to help
>> compile changelog fragments and compile them at time of delivery.
>> >> >
>> >> >
>> >> > I would prefer not to have the complexity of multiple files and an
>> added tool to the release process. I do not have a strong opinion though.
>> If others prefer we can switch to this tool. One nice benefit of this tool
>> would be to avoid merge conflicts if many different PRs edit the change log
>> file all at the same time in a conflicting way.
>> >> >
>> >> >>
>> >> >>
>> >> >> I came across this when working on the python-attrs[2] project,
>> which has some good documentation for contributors on how to use it:
>> https://www.attrs.org/en/stable/contributing.html#changelog
>> >> >>
>> >> >>
>> >> >> [1] https://github.com/hawkowl/towncrier
>> >> >> [2] https://github.com/python-attrs/attrs
>> >> >>
>> >> >>
>> >> >> On Fri, Jan 31, 2020 at 5:09 PM Ahmet Altay <al...@google.com>
>> wrote:
>> >> >>>
>> >> >>> Thank you for the quick responses. I sent out
>> https://github.com/apache/beam/pull/10743 to make this change. Please
>> provide feedback or directly edit the PR.
>> >> >>>
>> >> >>>
>> >> >>> On Fri, Jan 31, 2020 at 3:58 PM Robert Bradshaw <
>> robertwb@google.com> wrote:
>> >> >>>>
>> >> >>>> Yes, yes, yes! This is the one model of release notes that I've
>> >> >>>> actually seen work well at scale.
>> >> >>>>
>> >> >>>>
>> https://lists.apache.org/thread.html/41e03ace17dbcccf7e267ba6d538736b2a99a8e73e7fb45702766b17%40%3Cdev.beam.apache.org%3E
>> >> >>>>
>> >> >>>> Let's make it happen.
>> >> >>>>
>> >> >>>> On Fri, Jan 31, 2020 at 3:47 PM Robert Burke <ro...@frantil.com>
>> wrote:
>> >> >>>> >
>> >> >>>> > I like this suggestion, Jira titles and commit summaries don't
>> necessarily reflect the user impact for a given change (or set of changes).
>> Being able to see the Forest instead of the trees.
>> >> >>>> >
>> >> >>>> > On Fri, Jan 31, 2020, 3:37 PM Kenneth Knowles <ke...@apache.org>
>> wrote:
>> >> >>>> >>
>> >> >>>> >> +1
>> >> >>>> >>
>> >> >>>> >> This is a great idea. Hope it can lead to higher-value view of
>> relevant changes.
>> >> >>>> >>
>> >> >>>> >> I like it being in the root of the repo, so it lives next to
>> the code.
>> >> >>>> >>
>> >> >>>> >> Since the website is also markdown, it could be copied over
>> directly at release time, so it can be browsed there, too.
>> >> >>>> >>
>> >> >>>> >> Kenn
>> >> >>>> >>
>> >> >>>> >> On Fri, Jan 31, 2020 at 3:16 PM Ahmet Altay <al...@google.com>
>> wrote:
>> >> >>>> >>>
>> >> >>>> >>> Hi all,
>> >> >>>> >>>
>> >> >>>> >>> We currently have two major ways to communicate changes in a
>> release:
>> >> >>>> >>> - A blog post, to highlight major changes in the release.
>> (Example for 2.17: [1])
>> >> >>>> >>> - JIRA release notes pages listing all issues tagged for a
>> specific release. (Example for 2.17 [2]).
>> >> >>>> >>>
>> >> >>>> >>> There are a few issues with this process:
>> >> >>>> >>> - It is difficult for the release manager to know what is
>> important, what is a breaking change, what is dependency change etc. For
>> example, there were more than 150 Jira issues tagged for 2.17 release.
>> >> >>>> >>> - Release blog has many items, and does not necessarily
>> communicate important changes. It is difficult for users to discover major
>> changes short of going through a large list.
>> >> >>>> >>> - People involved in authoring or reviewing a PRs usually
>> have the most context about the change, and they are not necessarily
>> involved in the release process to provide this additional information.
>> >> >>>> >>>
>> >> >>>> >>> Would it be helpful if we maintain a simple change list file
>> and update it as part of the PRs with noteworthy changes? Release managers
>> could use this information as is in their blog posts (or link to it). Users
>> will have a single place to find highlights from various versions.
>> >> >>>> >>>
>> >> >>>> >>> Concretely, I am proposing:
>> >> >>>> >>> - Adding a CHANGES file to the root of the repository. (Name
>> could be anything, TFX uses RELEASE.md in their repo. [3])
>> >> >>>> >>> - Ask PR authors to update this file as part of their PR
>> whenever it makes sense
>> >> >>>> >>> - Reference this file during the release process, and a new
>> section for the next release after each release.
>> >> >>>> >>>
>> >> >>>> >>> Ahmet
>> >> >>>> >>>
>> >> >>>> >>> [1] https://beam.apache.org/blog/2020/01/06/beam-2.17.0.html
>> >> >>>> >>> [2]
>> https://issues.apache.org/jira/secure/ReleaseNote.jspa?version=12345970&projectId=12319527
>> >> >>>> >>> [3] https://github.com/tensorflow/tfx/blob/master/RELEASE.md
>>
>
Re: [DISCUSSION] Improve release notes by adding a change list file
Posted by Udi Meiri <eh...@google.com>.
+1 to add this to the checklist
On Mon, Feb 3, 2020 at 4:57 PM Robert Bradshaw <ro...@google.com> wrote:
> On Mon, Feb 3, 2020 at 4:49 PM Ahmet Altay <al...@google.com> wrote:
> >
> > On Mon, Feb 3, 2020 at 2:09 PM Robert Bradshaw <ro...@google.com>
> wrote:
> >>
> >> I would suggest we start with the simpler single file. If merge
> >> conflicts become an issue, we could look at other options, but I think
> >> it's worth keeping in mind that what we're trying to produce here is a
> >> single, higher-level, cohesive summary of the release rather than a
> >> 1:1 listing of commits, pull request, or jira entries (which we can
> >> link to). While new features often merit their own bullet points, this
> >> will allow for entries such as "Several improvements to portability
> >> including ..."
> >
> > I agree. If there are no objections I will go ahead with the PR I
> proposed. It adds a single change log file to begin with.
> >
> > We would need all committers to help after that by asking PR authors to
> update this file whenever it makes sense.
>
> Yes. Should we add it to the PR template checklist?
>
> >> On Mon, Feb 3, 2020 at 1:55 PM Ahmet Altay <al...@google.com> wrote:
> >> >
> >> >
> >> >
> >> > On Sat, Feb 1, 2020 at 9:22 AM Chad Dombrova <ch...@gmail.com>
> wrote:
> >> >>
> >> >> In case it's of any use, there's a tool called towncrier[1] to help
> compile changelog fragments and compile them at time of delivery.
> >> >
> >> >
> >> > I would prefer not to have the complexity of multiple files and an
> added tool to the release process. I do not have a strong opinion though.
> If others prefer we can switch to this tool. One nice benefit of this tool
> would be to avoid merge conflicts if many different PRs edit the change log
> file all at the same time in a conflicting way.
> >> >
> >> >>
> >> >>
> >> >> I came across this when working on the python-attrs[2] project,
> which has some good documentation for contributors on how to use it:
> https://www.attrs.org/en/stable/contributing.html#changelog
> >> >>
> >> >>
> >> >> [1] https://github.com/hawkowl/towncrier
> >> >> [2] https://github.com/python-attrs/attrs
> >> >>
> >> >>
> >> >> On Fri, Jan 31, 2020 at 5:09 PM Ahmet Altay <al...@google.com>
> wrote:
> >> >>>
> >> >>> Thank you for the quick responses. I sent out
> https://github.com/apache/beam/pull/10743 to make this change. Please
> provide feedback or directly edit the PR.
> >> >>>
> >> >>>
> >> >>> On Fri, Jan 31, 2020 at 3:58 PM Robert Bradshaw <
> robertwb@google.com> wrote:
> >> >>>>
> >> >>>> Yes, yes, yes! This is the one model of release notes that I've
> >> >>>> actually seen work well at scale.
> >> >>>>
> >> >>>>
> https://lists.apache.org/thread.html/41e03ace17dbcccf7e267ba6d538736b2a99a8e73e7fb45702766b17%40%3Cdev.beam.apache.org%3E
> >> >>>>
> >> >>>> Let's make it happen.
> >> >>>>
> >> >>>> On Fri, Jan 31, 2020 at 3:47 PM Robert Burke <ro...@frantil.com>
> wrote:
> >> >>>> >
> >> >>>> > I like this suggestion, Jira titles and commit summaries don't
> necessarily reflect the user impact for a given change (or set of changes).
> Being able to see the Forest instead of the trees.
> >> >>>> >
> >> >>>> > On Fri, Jan 31, 2020, 3:37 PM Kenneth Knowles <ke...@apache.org>
> wrote:
> >> >>>> >>
> >> >>>> >> +1
> >> >>>> >>
> >> >>>> >> This is a great idea. Hope it can lead to higher-value view of
> relevant changes.
> >> >>>> >>
> >> >>>> >> I like it being in the root of the repo, so it lives next to
> the code.
> >> >>>> >>
> >> >>>> >> Since the website is also markdown, it could be copied over
> directly at release time, so it can be browsed there, too.
> >> >>>> >>
> >> >>>> >> Kenn
> >> >>>> >>
> >> >>>> >> On Fri, Jan 31, 2020 at 3:16 PM Ahmet Altay <al...@google.com>
> wrote:
> >> >>>> >>>
> >> >>>> >>> Hi all,
> >> >>>> >>>
> >> >>>> >>> We currently have two major ways to communicate changes in a
> release:
> >> >>>> >>> - A blog post, to highlight major changes in the release.
> (Example for 2.17: [1])
> >> >>>> >>> - JIRA release notes pages listing all issues tagged for a
> specific release. (Example for 2.17 [2]).
> >> >>>> >>>
> >> >>>> >>> There are a few issues with this process:
> >> >>>> >>> - It is difficult for the release manager to know what is
> important, what is a breaking change, what is dependency change etc. For
> example, there were more than 150 Jira issues tagged for 2.17 release.
> >> >>>> >>> - Release blog has many items, and does not necessarily
> communicate important changes. It is difficult for users to discover major
> changes short of going through a large list.
> >> >>>> >>> - People involved in authoring or reviewing a PRs usually have
> the most context about the change, and they are not necessarily involved in
> the release process to provide this additional information.
> >> >>>> >>>
> >> >>>> >>> Would it be helpful if we maintain a simple change list file
> and update it as part of the PRs with noteworthy changes? Release managers
> could use this information as is in their blog posts (or link to it). Users
> will have a single place to find highlights from various versions.
> >> >>>> >>>
> >> >>>> >>> Concretely, I am proposing:
> >> >>>> >>> - Adding a CHANGES file to the root of the repository. (Name
> could be anything, TFX uses RELEASE.md in their repo. [3])
> >> >>>> >>> - Ask PR authors to update this file as part of their PR
> whenever it makes sense
> >> >>>> >>> - Reference this file during the release process, and a new
> section for the next release after each release.
> >> >>>> >>>
> >> >>>> >>> Ahmet
> >> >>>> >>>
> >> >>>> >>> [1] https://beam.apache.org/blog/2020/01/06/beam-2.17.0.html
> >> >>>> >>> [2]
> https://issues.apache.org/jira/secure/ReleaseNote.jspa?version=12345970&projectId=12319527
> >> >>>> >>> [3] https://github.com/tensorflow/tfx/blob/master/RELEASE.md
>
Re: [DISCUSSION] Improve release notes by adding a change list file
Posted by Robert Bradshaw <ro...@google.com>.
On Mon, Feb 3, 2020 at 4:49 PM Ahmet Altay <al...@google.com> wrote:
>
> On Mon, Feb 3, 2020 at 2:09 PM Robert Bradshaw <ro...@google.com> wrote:
>>
>> I would suggest we start with the simpler single file. If merge
>> conflicts become an issue, we could look at other options, but I think
>> it's worth keeping in mind that what we're trying to produce here is a
>> single, higher-level, cohesive summary of the release rather than a
>> 1:1 listing of commits, pull request, or jira entries (which we can
>> link to). While new features often merit their own bullet points, this
>> will allow for entries such as "Several improvements to portability
>> including ..."
>
> I agree. If there are no objections I will go ahead with the PR I proposed. It adds a single change log file to begin with.
>
> We would need all committers to help after that by asking PR authors to update this file whenever it makes sense.
Yes. Should we add it to the PR template checklist?
>> On Mon, Feb 3, 2020 at 1:55 PM Ahmet Altay <al...@google.com> wrote:
>> >
>> >
>> >
>> > On Sat, Feb 1, 2020 at 9:22 AM Chad Dombrova <ch...@gmail.com> wrote:
>> >>
>> >> In case it's of any use, there's a tool called towncrier[1] to help compile changelog fragments and compile them at time of delivery.
>> >
>> >
>> > I would prefer not to have the complexity of multiple files and an added tool to the release process. I do not have a strong opinion though. If others prefer we can switch to this tool. One nice benefit of this tool would be to avoid merge conflicts if many different PRs edit the change log file all at the same time in a conflicting way.
>> >
>> >>
>> >>
>> >> I came across this when working on the python-attrs[2] project, which has some good documentation for contributors on how to use it: https://www.attrs.org/en/stable/contributing.html#changelog
>> >>
>> >>
>> >> [1] https://github.com/hawkowl/towncrier
>> >> [2] https://github.com/python-attrs/attrs
>> >>
>> >>
>> >> On Fri, Jan 31, 2020 at 5:09 PM Ahmet Altay <al...@google.com> wrote:
>> >>>
>> >>> Thank you for the quick responses. I sent out https://github.com/apache/beam/pull/10743 to make this change. Please provide feedback or directly edit the PR.
>> >>>
>> >>>
>> >>> On Fri, Jan 31, 2020 at 3:58 PM Robert Bradshaw <ro...@google.com> wrote:
>> >>>>
>> >>>> Yes, yes, yes! This is the one model of release notes that I've
>> >>>> actually seen work well at scale.
>> >>>>
>> >>>> https://lists.apache.org/thread.html/41e03ace17dbcccf7e267ba6d538736b2a99a8e73e7fb45702766b17%40%3Cdev.beam.apache.org%3E
>> >>>>
>> >>>> Let's make it happen.
>> >>>>
>> >>>> On Fri, Jan 31, 2020 at 3:47 PM Robert Burke <ro...@frantil.com> wrote:
>> >>>> >
>> >>>> > I like this suggestion, Jira titles and commit summaries don't necessarily reflect the user impact for a given change (or set of changes). Being able to see the Forest instead of the trees.
>> >>>> >
>> >>>> > On Fri, Jan 31, 2020, 3:37 PM Kenneth Knowles <ke...@apache.org> wrote:
>> >>>> >>
>> >>>> >> +1
>> >>>> >>
>> >>>> >> This is a great idea. Hope it can lead to higher-value view of relevant changes.
>> >>>> >>
>> >>>> >> I like it being in the root of the repo, so it lives next to the code.
>> >>>> >>
>> >>>> >> Since the website is also markdown, it could be copied over directly at release time, so it can be browsed there, too.
>> >>>> >>
>> >>>> >> Kenn
>> >>>> >>
>> >>>> >> On Fri, Jan 31, 2020 at 3:16 PM Ahmet Altay <al...@google.com> wrote:
>> >>>> >>>
>> >>>> >>> Hi all,
>> >>>> >>>
>> >>>> >>> We currently have two major ways to communicate changes in a release:
>> >>>> >>> - A blog post, to highlight major changes in the release. (Example for 2.17: [1])
>> >>>> >>> - JIRA release notes pages listing all issues tagged for a specific release. (Example for 2.17 [2]).
>> >>>> >>>
>> >>>> >>> There are a few issues with this process:
>> >>>> >>> - It is difficult for the release manager to know what is important, what is a breaking change, what is dependency change etc. For example, there were more than 150 Jira issues tagged for 2.17 release.
>> >>>> >>> - Release blog has many items, and does not necessarily communicate important changes. It is difficult for users to discover major changes short of going through a large list.
>> >>>> >>> - People involved in authoring or reviewing a PRs usually have the most context about the change, and they are not necessarily involved in the release process to provide this additional information.
>> >>>> >>>
>> >>>> >>> Would it be helpful if we maintain a simple change list file and update it as part of the PRs with noteworthy changes? Release managers could use this information as is in their blog posts (or link to it). Users will have a single place to find highlights from various versions.
>> >>>> >>>
>> >>>> >>> Concretely, I am proposing:
>> >>>> >>> - Adding a CHANGES file to the root of the repository. (Name could be anything, TFX uses RELEASE.md in their repo. [3])
>> >>>> >>> - Ask PR authors to update this file as part of their PR whenever it makes sense
>> >>>> >>> - Reference this file during the release process, and a new section for the next release after each release.
>> >>>> >>>
>> >>>> >>> Ahmet
>> >>>> >>>
>> >>>> >>> [1] https://beam.apache.org/blog/2020/01/06/beam-2.17.0.html
>> >>>> >>> [2] https://issues.apache.org/jira/secure/ReleaseNote.jspa?version=12345970&projectId=12319527
>> >>>> >>> [3] https://github.com/tensorflow/tfx/blob/master/RELEASE.md
Re: [DISCUSSION] Improve release notes by adding a change list file
Posted by Ahmet Altay <al...@google.com>.
On Mon, Feb 3, 2020 at 2:09 PM Robert Bradshaw <ro...@google.com> wrote:
> I would suggest we start with the simpler single file. If merge
> conflicts become an issue, we could look at other options, but I think
> it's worth keeping in mind that what we're trying to produce here is a
> single, higher-level, cohesive summary of the release rather than a
> 1:1 listing of commits, pull request, or jira entries (which we can
> link to). While new features often merit their own bullet points, this
> will allow for entries such as "Several improvements to portability
> including ..."
>
I agree. If there are no objections I will go ahead with the PR I proposed.
It adds a single change log file to begin with.
We would need all committers to help after that by asking PR authors to
update this file whenever it makes sense.
>
> On Mon, Feb 3, 2020 at 1:55 PM Ahmet Altay <al...@google.com> wrote:
> >
> >
> >
> > On Sat, Feb 1, 2020 at 9:22 AM Chad Dombrova <ch...@gmail.com> wrote:
> >>
> >> In case it's of any use, there's a tool called towncrier[1] to help
> compile changelog fragments and compile them at time of delivery.
> >
> >
> > I would prefer not to have the complexity of multiple files and an added
> tool to the release process. I do not have a strong opinion though. If
> others prefer we can switch to this tool. One nice benefit of this tool
> would be to avoid merge conflicts if many different PRs edit the change log
> file all at the same time in a conflicting way.
> >
> >>
> >>
> >> I came across this when working on the python-attrs[2] project, which
> has some good documentation for contributors on how to use it:
> https://www.attrs.org/en/stable/contributing.html#changelog
> >>
> >>
> >> [1] https://github.com/hawkowl/towncrier
> >> [2] https://github.com/python-attrs/attrs
> >>
> >>
> >> On Fri, Jan 31, 2020 at 5:09 PM Ahmet Altay <al...@google.com> wrote:
> >>>
> >>> Thank you for the quick responses. I sent out
> https://github.com/apache/beam/pull/10743 to make this change. Please
> provide feedback or directly edit the PR.
> >>>
> >>>
> >>> On Fri, Jan 31, 2020 at 3:58 PM Robert Bradshaw <ro...@google.com>
> wrote:
> >>>>
> >>>> Yes, yes, yes! This is the one model of release notes that I've
> >>>> actually seen work well at scale.
> >>>>
> >>>>
> https://lists.apache.org/thread.html/41e03ace17dbcccf7e267ba6d538736b2a99a8e73e7fb45702766b17%40%3Cdev.beam.apache.org%3E
> >>>>
> >>>> Let's make it happen.
> >>>>
> >>>> On Fri, Jan 31, 2020 at 3:47 PM Robert Burke <ro...@frantil.com>
> wrote:
> >>>> >
> >>>> > I like this suggestion, Jira titles and commit summaries don't
> necessarily reflect the user impact for a given change (or set of changes).
> Being able to see the Forest instead of the trees.
> >>>> >
> >>>> > On Fri, Jan 31, 2020, 3:37 PM Kenneth Knowles <ke...@apache.org>
> wrote:
> >>>> >>
> >>>> >> +1
> >>>> >>
> >>>> >> This is a great idea. Hope it can lead to higher-value view of
> relevant changes.
> >>>> >>
> >>>> >> I like it being in the root of the repo, so it lives next to the
> code.
> >>>> >>
> >>>> >> Since the website is also markdown, it could be copied over
> directly at release time, so it can be browsed there, too.
> >>>> >>
> >>>> >> Kenn
> >>>> >>
> >>>> >> On Fri, Jan 31, 2020 at 3:16 PM Ahmet Altay <al...@google.com>
> wrote:
> >>>> >>>
> >>>> >>> Hi all,
> >>>> >>>
> >>>> >>> We currently have two major ways to communicate changes in a
> release:
> >>>> >>> - A blog post, to highlight major changes in the release.
> (Example for 2.17: [1])
> >>>> >>> - JIRA release notes pages listing all issues tagged for a
> specific release. (Example for 2.17 [2]).
> >>>> >>>
> >>>> >>> There are a few issues with this process:
> >>>> >>> - It is difficult for the release manager to know what is
> important, what is a breaking change, what is dependency change etc. For
> example, there were more than 150 Jira issues tagged for 2.17 release.
> >>>> >>> - Release blog has many items, and does not necessarily
> communicate important changes. It is difficult for users to discover major
> changes short of going through a large list.
> >>>> >>> - People involved in authoring or reviewing a PRs usually have
> the most context about the change, and they are not necessarily involved in
> the release process to provide this additional information.
> >>>> >>>
> >>>> >>> Would it be helpful if we maintain a simple change list file and
> update it as part of the PRs with noteworthy changes? Release managers
> could use this information as is in their blog posts (or link to it). Users
> will have a single place to find highlights from various versions.
> >>>> >>>
> >>>> >>> Concretely, I am proposing:
> >>>> >>> - Adding a CHANGES file to the root of the repository. (Name
> could be anything, TFX uses RELEASE.md in their repo. [3])
> >>>> >>> - Ask PR authors to update this file as part of their PR whenever
> it makes sense
> >>>> >>> - Reference this file during the release process, and a new
> section for the next release after each release.
> >>>> >>>
> >>>> >>> Ahmet
> >>>> >>>
> >>>> >>> [1] https://beam.apache.org/blog/2020/01/06/beam-2.17.0.html
> >>>> >>> [2]
> https://issues.apache.org/jira/secure/ReleaseNote.jspa?version=12345970&projectId=12319527
> >>>> >>> [3] https://github.com/tensorflow/tfx/blob/master/RELEASE.md
>
Re: [DISCUSSION] Improve release notes by adding a change list file
Posted by Robert Bradshaw <ro...@google.com>.
I would suggest we start with the simpler single file. If merge
conflicts become an issue, we could look at other options, but I think
it's worth keeping in mind that what we're trying to produce here is a
single, higher-level, cohesive summary of the release rather than a
1:1 listing of commits, pull request, or jira entries (which we can
link to). While new features often merit their own bullet points, this
will allow for entries such as "Several improvements to portability
including ..."
On Mon, Feb 3, 2020 at 1:55 PM Ahmet Altay <al...@google.com> wrote:
>
>
>
> On Sat, Feb 1, 2020 at 9:22 AM Chad Dombrova <ch...@gmail.com> wrote:
>>
>> In case it's of any use, there's a tool called towncrier[1] to help compile changelog fragments and compile them at time of delivery.
>
>
> I would prefer not to have the complexity of multiple files and an added tool to the release process. I do not have a strong opinion though. If others prefer we can switch to this tool. One nice benefit of this tool would be to avoid merge conflicts if many different PRs edit the change log file all at the same time in a conflicting way.
>
>>
>>
>> I came across this when working on the python-attrs[2] project, which has some good documentation for contributors on how to use it: https://www.attrs.org/en/stable/contributing.html#changelog
>>
>>
>> [1] https://github.com/hawkowl/towncrier
>> [2] https://github.com/python-attrs/attrs
>>
>>
>> On Fri, Jan 31, 2020 at 5:09 PM Ahmet Altay <al...@google.com> wrote:
>>>
>>> Thank you for the quick responses. I sent out https://github.com/apache/beam/pull/10743 to make this change. Please provide feedback or directly edit the PR.
>>>
>>>
>>> On Fri, Jan 31, 2020 at 3:58 PM Robert Bradshaw <ro...@google.com> wrote:
>>>>
>>>> Yes, yes, yes! This is the one model of release notes that I've
>>>> actually seen work well at scale.
>>>>
>>>> https://lists.apache.org/thread.html/41e03ace17dbcccf7e267ba6d538736b2a99a8e73e7fb45702766b17%40%3Cdev.beam.apache.org%3E
>>>>
>>>> Let's make it happen.
>>>>
>>>> On Fri, Jan 31, 2020 at 3:47 PM Robert Burke <ro...@frantil.com> wrote:
>>>> >
>>>> > I like this suggestion, Jira titles and commit summaries don't necessarily reflect the user impact for a given change (or set of changes). Being able to see the Forest instead of the trees.
>>>> >
>>>> > On Fri, Jan 31, 2020, 3:37 PM Kenneth Knowles <ke...@apache.org> wrote:
>>>> >>
>>>> >> +1
>>>> >>
>>>> >> This is a great idea. Hope it can lead to higher-value view of relevant changes.
>>>> >>
>>>> >> I like it being in the root of the repo, so it lives next to the code.
>>>> >>
>>>> >> Since the website is also markdown, it could be copied over directly at release time, so it can be browsed there, too.
>>>> >>
>>>> >> Kenn
>>>> >>
>>>> >> On Fri, Jan 31, 2020 at 3:16 PM Ahmet Altay <al...@google.com> wrote:
>>>> >>>
>>>> >>> Hi all,
>>>> >>>
>>>> >>> We currently have two major ways to communicate changes in a release:
>>>> >>> - A blog post, to highlight major changes in the release. (Example for 2.17: [1])
>>>> >>> - JIRA release notes pages listing all issues tagged for a specific release. (Example for 2.17 [2]).
>>>> >>>
>>>> >>> There are a few issues with this process:
>>>> >>> - It is difficult for the release manager to know what is important, what is a breaking change, what is dependency change etc. For example, there were more than 150 Jira issues tagged for 2.17 release.
>>>> >>> - Release blog has many items, and does not necessarily communicate important changes. It is difficult for users to discover major changes short of going through a large list.
>>>> >>> - People involved in authoring or reviewing a PRs usually have the most context about the change, and they are not necessarily involved in the release process to provide this additional information.
>>>> >>>
>>>> >>> Would it be helpful if we maintain a simple change list file and update it as part of the PRs with noteworthy changes? Release managers could use this information as is in their blog posts (or link to it). Users will have a single place to find highlights from various versions.
>>>> >>>
>>>> >>> Concretely, I am proposing:
>>>> >>> - Adding a CHANGES file to the root of the repository. (Name could be anything, TFX uses RELEASE.md in their repo. [3])
>>>> >>> - Ask PR authors to update this file as part of their PR whenever it makes sense
>>>> >>> - Reference this file during the release process, and a new section for the next release after each release.
>>>> >>>
>>>> >>> Ahmet
>>>> >>>
>>>> >>> [1] https://beam.apache.org/blog/2020/01/06/beam-2.17.0.html
>>>> >>> [2] https://issues.apache.org/jira/secure/ReleaseNote.jspa?version=12345970&projectId=12319527
>>>> >>> [3] https://github.com/tensorflow/tfx/blob/master/RELEASE.md
Re: [DISCUSSION] Improve release notes by adding a change list file
Posted by Ahmet Altay <al...@google.com>.
On Sat, Feb 1, 2020 at 9:22 AM Chad Dombrova <ch...@gmail.com> wrote:
> In case it's of any use, there's a tool called towncrier[1] to help
> compile changelog fragments and compile them at time of delivery.
>
I would prefer not to have the complexity of multiple files and an added
tool to the release process. I do not have a strong opinion though. If
others prefer we can switch to this tool. One nice benefit of this tool
would be to avoid merge conflicts if many different PRs edit the change log
file all at the same time in a conflicting way.
>
> I came across this when working on the python-attrs[2] project, which has
> some good documentation for contributors on how to use it:
> https://www.attrs.org/en/stable/contributing.html#changelog
> <https://www.attrs.org/en/stable/contributing.html#changelog>
>
>
> [1] https://github.com/hawkowl/towncrier
> [2] https://github.com/python-attrs/attrs
>
>
> On Fri, Jan 31, 2020 at 5:09 PM Ahmet Altay <al...@google.com> wrote:
>
>> Thank you for the quick responses. I sent out
>> https://github.com/apache/beam/pull/10743 to make this change. Please
>> provide feedback or directly edit the PR.
>>
>
>> On Fri, Jan 31, 2020 at 3:58 PM Robert Bradshaw <ro...@google.com>
>> wrote:
>>
>>> Yes, yes, yes! This is the one model of release notes that I've
>>> actually seen work well at scale.
>>>
>>>
>>> https://lists.apache.org/thread.html/41e03ace17dbcccf7e267ba6d538736b2a99a8e73e7fb45702766b17%40%3Cdev.beam.apache.org%3E
>>>
>>> Let's make it happen.
>>>
>>> On Fri, Jan 31, 2020 at 3:47 PM Robert Burke <ro...@frantil.com> wrote:
>>> >
>>> > I like this suggestion, Jira titles and commit summaries don't
>>> necessarily reflect the user impact for a given change (or set of changes).
>>> Being able to see the Forest instead of the trees.
>>> >
>>> > On Fri, Jan 31, 2020, 3:37 PM Kenneth Knowles <ke...@apache.org> wrote:
>>> >>
>>> >> +1
>>> >>
>>> >> This is a great idea. Hope it can lead to higher-value view of
>>> relevant changes.
>>> >>
>>> >> I like it being in the root of the repo, so it lives next to the code.
>>> >>
>>> >> Since the website is also markdown, it could be copied over directly
>>> at release time, so it can be browsed there, too.
>>> >>
>>> >> Kenn
>>> >>
>>> >> On Fri, Jan 31, 2020 at 3:16 PM Ahmet Altay <al...@google.com> wrote:
>>> >>>
>>> >>> Hi all,
>>> >>>
>>> >>> We currently have two major ways to communicate changes in a release:
>>> >>> - A blog post, to highlight major changes in the release. (Example
>>> for 2.17: [1])
>>> >>> - JIRA release notes pages listing all issues tagged for a specific
>>> release. (Example for 2.17 [2]).
>>> >>>
>>> >>> There are a few issues with this process:
>>> >>> - It is difficult for the release manager to know what is important,
>>> what is a breaking change, what is dependency change etc. For example,
>>> there were more than 150 Jira issues tagged for 2.17 release.
>>> >>> - Release blog has many items, and does not necessarily communicate
>>> important changes. It is difficult for users to discover major changes
>>> short of going through a large list.
>>> >>> - People involved in authoring or reviewing a PRs usually have the
>>> most context about the change, and they are not necessarily involved in the
>>> release process to provide this additional information.
>>> >>>
>>> >>> Would it be helpful if we maintain a simple change list file and
>>> update it as part of the PRs with noteworthy changes? Release managers
>>> could use this information as is in their blog posts (or link to it). Users
>>> will have a single place to find highlights from various versions.
>>> >>>
>>> >>> Concretely, I am proposing:
>>> >>> - Adding a CHANGES file to the root of the repository. (Name could
>>> be anything, TFX uses RELEASE.md in their repo. [3])
>>> >>> - Ask PR authors to update this file as part of their PR whenever it
>>> makes sense
>>> >>> - Reference this file during the release process, and a new section
>>> for the next release after each release.
>>> >>>
>>> >>> Ahmet
>>> >>>
>>> >>> [1] https://beam.apache.org/blog/2020/01/06/beam-2.17.0.html
>>> >>> [2]
>>> https://issues.apache.org/jira/secure/ReleaseNote.jspa?version=12345970&projectId=12319527
>>> >>> [3] https://github.com/tensorflow/tfx/blob/master/RELEASE.md
>>>
>>
Re: [DISCUSSION] Improve release notes by adding a change list file
Posted by Chad Dombrova <ch...@gmail.com>.
In case it's of any use, there's a tool called towncrier[1] to help compile
changelog fragments and compile them at time of delivery.
I came across this when working on the python-attrs[2] project, which has
some good documentation for contributors on how to use it:
https://www.attrs.org/en/stable/contributing.html#changelog
<https://www.attrs.org/en/stable/contributing.html#changelog>
[1] https://github.com/hawkowl/towncrier
[2] https://github.com/python-attrs/attrs
On Fri, Jan 31, 2020 at 5:09 PM Ahmet Altay <al...@google.com> wrote:
> Thank you for the quick responses. I sent out
> https://github.com/apache/beam/pull/10743 to make this change. Please
> provide feedback or directly edit the PR.
>
> On Fri, Jan 31, 2020 at 3:58 PM Robert Bradshaw <ro...@google.com>
> wrote:
>
>> Yes, yes, yes! This is the one model of release notes that I've
>> actually seen work well at scale.
>>
>>
>> https://lists.apache.org/thread.html/41e03ace17dbcccf7e267ba6d538736b2a99a8e73e7fb45702766b17%40%3Cdev.beam.apache.org%3E
>>
>> Let's make it happen.
>>
>> On Fri, Jan 31, 2020 at 3:47 PM Robert Burke <ro...@frantil.com> wrote:
>> >
>> > I like this suggestion, Jira titles and commit summaries don't
>> necessarily reflect the user impact for a given change (or set of changes).
>> Being able to see the Forest instead of the trees.
>> >
>> > On Fri, Jan 31, 2020, 3:37 PM Kenneth Knowles <ke...@apache.org> wrote:
>> >>
>> >> +1
>> >>
>> >> This is a great idea. Hope it can lead to higher-value view of
>> relevant changes.
>> >>
>> >> I like it being in the root of the repo, so it lives next to the code.
>> >>
>> >> Since the website is also markdown, it could be copied over directly
>> at release time, so it can be browsed there, too.
>> >>
>> >> Kenn
>> >>
>> >> On Fri, Jan 31, 2020 at 3:16 PM Ahmet Altay <al...@google.com> wrote:
>> >>>
>> >>> Hi all,
>> >>>
>> >>> We currently have two major ways to communicate changes in a release:
>> >>> - A blog post, to highlight major changes in the release. (Example
>> for 2.17: [1])
>> >>> - JIRA release notes pages listing all issues tagged for a specific
>> release. (Example for 2.17 [2]).
>> >>>
>> >>> There are a few issues with this process:
>> >>> - It is difficult for the release manager to know what is important,
>> what is a breaking change, what is dependency change etc. For example,
>> there were more than 150 Jira issues tagged for 2.17 release.
>> >>> - Release blog has many items, and does not necessarily communicate
>> important changes. It is difficult for users to discover major changes
>> short of going through a large list.
>> >>> - People involved in authoring or reviewing a PRs usually have the
>> most context about the change, and they are not necessarily involved in the
>> release process to provide this additional information.
>> >>>
>> >>> Would it be helpful if we maintain a simple change list file and
>> update it as part of the PRs with noteworthy changes? Release managers
>> could use this information as is in their blog posts (or link to it). Users
>> will have a single place to find highlights from various versions.
>> >>>
>> >>> Concretely, I am proposing:
>> >>> - Adding a CHANGES file to the root of the repository. (Name could be
>> anything, TFX uses RELEASE.md in their repo. [3])
>> >>> - Ask PR authors to update this file as part of their PR whenever it
>> makes sense
>> >>> - Reference this file during the release process, and a new section
>> for the next release after each release.
>> >>>
>> >>> Ahmet
>> >>>
>> >>> [1] https://beam.apache.org/blog/2020/01/06/beam-2.17.0.html
>> >>> [2]
>> https://issues.apache.org/jira/secure/ReleaseNote.jspa?version=12345970&projectId=12319527
>> >>> [3] https://github.com/tensorflow/tfx/blob/master/RELEASE.md
>>
>