Introduce towncrier

[Gitznik]

• I have added an entry to docs/changelog.md

Summary of changes

As suggested in #1161, this introduces towncrier for managing the changelog. @chrysle I hope you're fine with me doing some work on this. I really wanted to stop having conflicts in the changelog ;)

I've updated the changelog for all releases since 1.0, excluding linking the issues.

I've updated the current open changelog entries to be towncrier news fragements.

I've pretty much stuck to the default configuration suggested by towncrier. Please let me know if you have any other preferences.

Closes #1161.

The current open changelog items would be added to the changelog like this:
towncrier build --version 1.5.0

1.5.0 - 2024-01-11

Added

• Allow skipping maintenance tasks during list command (#1081)
• Include into (zipapp) so that it can be executed with Python 3.10 or earlier (#1142)
• Introduce towncrier for managing the changelog (#1161)

Changed

• Update on scripts using and no table following the updated version of PEP 723 (#1180)
• Update pipx run on scripts using /// script and no run table following the updated version of PEP 723 (#1180)

Fixed

• Raise more user friendly error when provided --python version is not found (#1089)
• pipx run: Verify whether the script name provided is a file before running it (#1152)
• Avoid repeated exception logging in a few rare cases (#1192)

[Gitznik]

Just realized this needs a bit more work like updating the CONTRIBUTING.md, so I'll mark this as draft for now.

[chrysle]

Thank you for working on this! I had already started this review so I'm submitting regardless of the draft status.

Yes, CONTRIBUTING.md will need to be updated. Also, we'll have to refactor our changelog CI process.

[gaborbernat]

Also needs https://github.com/pypa/pipx/blob/main/.github/workflows/tests.yml#L134 updated.

[Gitznik]

I have mostly copied the Submitting changes section from twine. Let me know what you think.

[Gitznik]

Also needs https://github.com/pypa/pipx/blob/main/.github/workflows/tests.yml#L134 updated.

I hope my change should be all that is necessary. Most other repos in pypa I have checked that use towncrier have a manual step to do the changelog build. Not sure if there's a reason for it.

[gaborbernat]

I hope my change should be all that is necessary. Most other repos in pypa I have checked that use towncrier have a manual step to do the changelog build. Not sure if there's a reason for it.

This project wants to avoid that. PyPA is not a unified project set, we each do what works best for us.

[gaborbernat]

You have some merge conflicts to resolve first 👍

[gaborbernat]

Can you add a changelog entry so we can see it showing up here https://pipx--1201.org.readthedocs.build/1201/changelog

Also I don't want to see this:

This project uses [towncrier](https://towncrier.readthedocs.io/) and the changes for the upcoming release can be found in https://github.com/twisted/my-project/tree/main/changelog.d/.

on the changelog entry.

Instead, we should change the doc generation to include it in-line. That way we can see how the changelog will look post release as part of the PR.

See virtualenv doing this https://github.com/pypa/virtualenv/blob/main/docs/conf.py#L54

[Gitznik]

Can you add a changelog entry so we can see it showing up here https://pipx--1201.org.readthedocs.build/1201/changelog

Also I don't want to see this:

This project uses [towncrier](https://towncrier.readthedocs.io/) and the changes for the upcoming release can be found in https://github.com/twisted/my-project/tree/main/changelog.d/.

on the changelog entry.

Instead, we should change the doc generation to include it in-line. That way we can see how the changelog will look post release as part of the PR.

See virtualenv doing this https://github.com/pypa/virtualenv/blob/main/docs/conf.py#L54

I've done this now. 2 things to note:

1. Changelog entries under type misc would not show the news fragment content in the current config, just a link to the issue number.
2. Running the nox build_docs command now modifies the changelog. This might lead to people accidentally committing changes to it, which would have to be monitored during PRs.

Please ignore conflicts in the CHANGELOG.md for now. Once everyone is happy with the implementation, I'll resolve them and convert the new changelog entries to news fragments.

Edit:
2. changed to now modify the changelog, but instead create a separate gitignored file that is just embedded in the changelog.

[Gitznik]

Thanks @gaborbernat @chrysle with your thorough support and suggestions for getting this out there :) Much appreciated!

[gaborbernat]

Thanks for making it happen 👍

[chrysle]

Thanks for making it happen 👍

I'm going along with that!

[gaborbernat]

This did fail in the latest release, see https://github.com/pypa/pipx/actions/runs/7544497267/job/20539252092 @Gitznik can you take a look please?

[chrysle]

Probably running towncrier with pipx is a problem?

[Gitznik]

Yeah I'm testing installing it first instead of running directly. That fixed the problem for me locally.