+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 >
smime.p7s
Description: S/MIME Cryptographic Signature
