I'm proposing some changes in how we release our changelog and updating docs, starting with core Airflow and the helm chart. After a while, if we are happy with the changes, these could also be applied to the providers.
First is combining the changelog and updating docs into a single "release notes" document. This gives our users a single place to see both "Significant Changes" and the list of notable user-facing changes. By "Significant Changes", I mean things someone updating to that version may need or want to know about (these may or may not be breaking changes) - essentially what goes in UPDATING currently. Secondly, I propose we give towncrier a trial run for the next few releases. This can (eventually) help spread out the work currently placed on the release manager by allowing "newsfragements" to be added in PRs, which are later combined automatically to build the release notes. PR authors and/or commiters can decide where a change should be in the release notes, if at all, while that PR is still fresh in everyone's minds. Now a quick towncrier example: I've just opened a PR, 1234, that fixes a bug. To add it to the changelog for the next release, I simply create a `newsfragements/1234.bugfix.rst` file with the contents "Fixed scheduler bug with ``max_active_runs``". For the next release, towncrier will automatically generate this: ``` Airflow 2.3.0 (2021-12-01) -------------------------- Bug Fixes ^^^^^^^^^ - Fixed scheduler bug with ``max_active_runs`` (#1234) ``` Couple things to note here: - The commit message subject and the release notes entry don't have to match (they have different audiences, after all) - The release notes entry can be modified later easily and durably (i.e. the release manager doesn't have to remember to do it manually later) - Works well with our cherry-picking workflow for bugfix releases (when towncrier builds the release notes, it deletes the newfragements it used, so we don't end up with duplicate entries - and these deletes can be cherry-picked back to main) This will certainly be a bit of a fluid process as we go through it the first few times, but it gives us a good foundation for being able to distribute the effort of building release notes and make it less of an afterthought. For now, creating a newsfragment in PRs will be optional, but as we prove out this process we could start requiring the release notes be handled before merging. Still on my todo list (doesn't necessarily have to happen _now_ though): - Automate reformatting significant changes from a list to sections - New release-manager specific tooling to help bulk-generate missing newsfragments - Minor tweaks to some other release-manager specific tooling (e.g. chart artifacthub changelog generator) Please check out the feature branch and experiment! I'm eager to hear your feedback. https://github.com/apache/airflow/pull/22003 Thanks, Jed
