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