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
