Tools --- we have several to mention; sp/changelist, towncrier, scipy wiki, astropy (two mechanisms? @pllim @bsipocz?)

actions to be used by either towncrier systems or by direct edits of a single changelog file (both approaches have legitime use cases):

https://github.com/scientific-python/action-towncrier-changelog
https://github.com/scientific-python/action-check-changelogfile

quasi-automation: I do run cosistency checking scripts before cutting a release to ensure all PRs in a release either have a changelog, or e.g. a no-changelog-required label. So in my mind the actions are required for the PR, but in practice there is always some inconsistencies, especially when there are many people doing merges with significantly different level of tolerance towards failing CI checks.

I think it would be useful to gather info from projects which use more niche workflows (like SciPy) on what stops them from moving to an automated tool, to help guide readers. There is generic dev workflow churn, but any other reasons are probably more informative.

@lucascolley Yes, there are always exemptions. Could you point me to the SciPy documentation that covers this part?

There is a bit of documentation at https://scipy.github.io/devdocs/dev/core-dev/index.html#release-notes. We recently also introduced a "needs-release-note" tag to try to reduce the chance that PRs are missed.

I would recommend adding a link to the PyPI instructions for automation here: https://packaging.python.org/en/latest/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows/

but this document is not about releasing, but just the changelog, and thus automation for me means e.g. the github actions checking the existence of a changelog, or the changelog framework itself, e.g. creating one single changelog file from the fragments for towncrier

In my mind, generating the changelog and the release are tightly coupled and usually happens at the same time, so for any automation to happen it would be in the same file. here is an example of an automated release pipeline generated with the above docs that also generates release notes automatically: https://github.com/duckdb/dbt-duckdb/blob/master/.github/workflows/release.yml

There is also a --notes tag that lets you add custom (generated or manually entered) notes

I like to have the changelog available, and complete/correct during the dev process already, it's quite useful for big projects, but I also find it somewhat useful to enforce the presence the changelog at the time a contribution is made

Slightly related and not sure myself: should changelogs link to API like functions etc when rendered by sphinx? This can be very nice from a user perspective but over time, these references tend to get stale pretty fast due to deprecations, etc. We should probably mention this trade-off in some capacity.

Yes, for that reason, astropy no longer put "live" links (especially intersphinx stuff) in changelog, so we don't have to go back and fix broken links N number of years later, and thus changing history (and if you type at 88mph, more bad things might also happen). Some URLs still snuck in and we handle those as need arise. Our decision had oppositions, so it is not perfect solution either.

We use nitpicky so any sphinx links in our changelog can often break with new releases. So that is a very common reason to edit our changelog.

Does "maintaining accuracy" include fixing typo?

Another thing @InessaPawson and I chatted about is to provide a template for a GitHub profile readme that shows OSS/Scientific Python contributions:
https://docs.github.com/en/account-and-profile/setting-up-and-managing-your-github-profile/customizing-your-profile/managing-your-profile-readme

@guenp After giving it more thought, I wonder if this info belongs to the SPEC about release documentation. I will keep the conversation open to gather feedack from others.

Should at least list some that are recommended (and give reasons why they are recommended)?