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