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