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