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