Use Towncrier to Manage Changelog

[seifertm]

Changelog management

The changelog has previously been maintained manually. This lead to avoidable merge conflicts, because of changelog patches. Moreover, it increases the roundtrip time for contributions, because contributors generally don't adjust the changelog which forces the maintainers to ask for an explicit changelog entry.

This patch uses towncrier to collect changelog entries and compile them during the release process.
TBD: Enforce changelog entries

Release notes

Previously, the release workflow attached the README as release notes. This is mostly unhelpful and results in length email notifications when a pytest-asyncio release is published.

This patch uses the annotation built Git tag as release notes. If the current build is not a Git tag, the compiled towncrier news fragments are published as release notes.

Closes #511

[codecov-commenter]

Codecov Report

All modified and coverable lines are covered by tests ✅

Project coverage is 90.84%. Comparing base (87f7d72) to head (36beff3).

Additional details and impacted files

@@           Coverage Diff           @@
##             main    #1102   +/-   ##
=======================================
  Coverage   90.84%   90.84%           
=======================================
  Files           2        2           
  Lines         579      579           
  Branches       77       77           
=======================================
  Hits          526      526           
  Misses         32       32           
  Partials       21       21           

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

[webknjaz]

Perhaps, you'd like to integrate sphinxcontrib-towncrier right away?

Also, here's better sections https://github.com/aio-libs/yarl/blob/60f99a1/towncrier.toml, better template https://github.com/aio-libs/yarl/blob/60f99a1/CHANGES/.TEMPLATE.rst and a readme https://github.com/aio-libs/yarl/blob/60f99a1/CHANGES/README.rst examples.

Also, a config for the change note enforcement bot: https://github.com/pytest-dev/pytest/blob/8173aa8/.github/chronographer.yml.

[seifertm]

Perhaps, you'd like to integrate sphinxcontrib-towncrier right away?

Thanks for pointing this out, I wasn't aware of the project! My understanding is that it provides a way to integrate towncrier drafts using a Sphinx directive. However, we recently disabled the latest (aka development version) documentation on readthedocs, because it was a repeated source of error (see for example #905 #1070). Therefore, I'm not sure what problem it solves for pytest-asyncio.

Also, here's better sections https://github.com/aio-libs/yarl/blob/60f99a1/towncrier.toml, better template https://github.com/aio-libs/yarl/blob/60f99a1/CHANGES/.TEMPLATE.rst and a readme https://github.com/aio-libs/yarl/blob/60f99a1/CHANGES/README.rst examples.

Fair enough. Let's revisit the types of news fragments. For example, we previously included changelog entries for downstream packagers, which is missing in the current config.

Ultimately, news fragments for contributors and downstream packagers should go into separate changelogs, in my opinion.

Also, a config for the change note enforcement bot: https://github.com/pytest-dev/pytest/blob/8173aa8/.github/chronographer.yml.

Chronographer is another thing I need to look into then :)

[webknjaz]

FWIW, all these are mine.. Let me know if you need help with anything.

sphinxcontrib-towncrier is also useful in local builds + PR builds to see if the changelog seems consistent and renders well. Additionally, because it makes unlinted disconnected documents a part of the Sphinx build, it allows catching syntax errors early or spellchecking with sphinxcontrib-spelling etc.