Skip to content

Use Towncrier to Manage Changelog #1102

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 4 commits into from
May 2, 2025

Conversation

seifertm
Copy link
Contributor

@seifertm seifertm commented Apr 28, 2025

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

@seifertm seifertm changed the title Use towncrier to manage Use Towncrier to Manage Changelog Apr 28, 2025
@seifertm seifertm force-pushed the add-towncrier-configuration branch from 7a1afc6 to b56c931 Compare April 28, 2025 17:34
@codecov-commenter
Copy link

codecov-commenter commented Apr 28, 2025

Codecov Report

All modified and coverable lines are covered by tests ✅

Project coverage is 90.84%. Comparing base (87f7d72) to head (3cdf4f3).
Report is 3 commits behind head on main.

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.

@seifertm seifertm force-pushed the add-towncrier-configuration branch 2 times, most recently from 90d67bf to 36beff3 Compare April 28, 2025 17:41
@webknjaz
Copy link
Member

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
Copy link
Contributor Author

seifertm commented Apr 28, 2025

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
Copy link
Member

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.

@seifertm seifertm added this to the v0.26 milestone May 1, 2025
@seifertm seifertm force-pushed the add-towncrier-configuration branch from d3e24d2 to 746f307 Compare May 1, 2025 13:57
@seifertm seifertm force-pushed the add-towncrier-configuration branch from 746f307 to 3cdf4f3 Compare May 1, 2025 14:01
@seifertm
Copy link
Contributor Author

seifertm commented May 1, 2025

Added a news fragment type for downstream packagers.

@webknjaz How can I add the Chronographer app to pytest-asyncio to try it out?
The link https://github.com/apps/chronographer just tells me that "Chronographer is a private Github App".

@seifertm seifertm marked this pull request as ready for review May 1, 2025 14:22
@seifertm seifertm requested review from asvetlov and Tinche as code owners May 1, 2025 14:22
@seifertm seifertm added this pull request to the merge queue May 2, 2025
Merged via the queue into pytest-dev:main with commit a2cce08 May 2, 2025
16 checks passed
@seifertm seifertm deleted the add-towncrier-configuration branch May 2, 2025 07:53
Copy link
Member

@webknjaz webknjaz left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@seifertm the app is https://github.com/apps/psf-chronographer. I also marked a mistake in this patch below.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Development

Successfully merging this pull request may close these issues.

Adjust releases so dependabot shows changelog entries
3 participants