Hey Leah, Part of my goal was to leave the "end result" substantially unchanged, except for our existing changelog and updating guide being combined together. For example, compare 2.2.4:
New: https://github.com/astronomer/airflow/blob/towncrier_changelogs/RELEASE_NOTES.rst#airflow-2-2-4-2022-02-22 Current: https://github.com/apache/airflow/blob/main/UPDATING.md#airflow-224 and https://github.com/apache/airflow/blob/main/CHANGELOG.txt#L1 For end users, that's the extent of the change, though over time I hope this will lead to better quality release notes too. For those developing Airflow, and thus (potentially/eventually) interacting with towncrier, the biggest win in my eyes is that we can have a different commit subject and release notes entry, and the latter can change after the fact easily. Here is an example from 2.2.4: https://github.com/apache/airflow/commit/2af0f700857cbf7401d930ff24cdff273b501beb Commit subject: Update v1.yaml (#21024 <https://github.com/apache/airflow/pull/21024>) The changelog entry ended up being the following, but only because I remembered to change it after generating the final changelog: Don't require dag_id in body in dagrun REST API endpoint (#21024) Currently we use the immutable commit subject, so situations like this or even simple typos require manual release manager intervention during the release process. I don't want the final quality of the changelog to be reliant on me remembering to do this type of thing, and it becomes even more problematic with minor releases due to the volume. With towncrier instead, ideally before the PR is merged this gets added to it: ``` echo "Don't require dag_id in body in dagrun REST API endpoint" > newsframents/21024.bugfix.rst ``` And even if it doesn't happen in the initial PR, once someone notices it can be added/changed after the fact _still_ before release time, leaving less "manual" action items. I encourage you to go experiment with it hands on, that might help it click! Here is a quick start :) (using the chart because it is "empty" at the moment) ``` # setup echo "Some new feature" > chart/newsfragments/1234.feature.rst echo "Another feature" > chart/newsfragments/2222.feature.rst echo "X, Y, and Z have been deprecated" > chart/newsfragments/3333.significant.rst echo "Fixed a bad bug" > chart/newsfragments/3333.bugfix.rst echo "New cool doc section" > chart/newsfragments/5555.doc.rst # preview towncrier build --draft --version=1.6.0 --date=2021-12-15 --dir chart --config chart/newsfragments/config.toml ``` Results in: ``` Airflow Helm Chart 1.6.0 (2021-12-15) ------------------------------------- Significant Changes ^^^^^^^^^^^^^^^^^^^ - X, Y, and Z have been deprecated (#3333) Features ^^^^^^^^ - Some new feature (#1234) - Another feature (#2222) Bug Fixes ^^^^^^^^^ - Fixed a bad bug (#3333) Doc only Changes ^^^^^^^^^^^^^^^^ - New cool doc section (#5555) ``` Commit the newfragments (`git add chart/newsfragments && git commit -m "demo" -n` ), then remove the `--draft` flag and observe the fragments are deleted and the release notes are in `chart/RELEASE_NOTES.rst`. Thanks, Jed
