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 <rober...@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 <rober...@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 <chad...@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 < >> rober...@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 <rob...@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 <k...@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 >> >
