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 >
