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