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