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
