(feat): use towncrier for changelog automations

[ilan-gold]

Blocked by twisted/towncrier#661 and twisted/towncrier#648 (comment).

Also, need to figure out exactly where to inject this into the CI. If not, this can be done manually, although I'd rather not.

I've set up the 0.10.9 release to use towncrier - so all you need to do is run towncrier before building the docs.

• Closes #
• Tests added
• Release note added (or unnecessary)

[codecov]

Codecov Report

All modified and coverable lines are covered by tests ✅

Project coverage is 84.25%. Comparing base (229e2a6) to head (dac333b).
Report is 1 commits behind head on main.

Additional details and impacted files

@@            Coverage Diff             @@
##             main    #1604      +/-   ##
==========================================
- Coverage   86.74%   84.25%   -2.49%     
==========================================
  Files          37       37              
  Lines        5989     5989              
==========================================
- Hits         5195     5046     -149     
- Misses        794      943     +149     

see 8 files with indirect coverage changes

[flying-sheep]

Wow, if that’s it, that looks extremely clean, seems instantly nicer than what we have now.

Also, need to figure out exactly where to inject this into the CI. If not, this can be done manually, although I'd rather not.

Ideally release-please style:

1. A workflow-generated PR¹ that contains the result of running towncrier to prepare a release. Two options for how it’s created:
   1. some workflow reacts to pushes on main and the current version branch by creating/updating a “do a patch release” PR and a “do a minor/major release” PR. The effect is two PRs always existing, except directly after a release¹.
   2. a manually run workflow with the dropdown choices “patch”, “minor”, “major” creates that PR
2. When that(/one of these) PRs is merged, a workflow creates Git tag, GitHub release, and PyPI release.

Footnotes

1. After merging the patch release PR, the minor/major PR would still be open. After merging the minor/major PR, the patch release PR gets auto-closed. ↩

[flying-sheep]

FYI: I pushed eefafad:

• This allows to just hatch run towncrier:

  anndata/hatch.toml

  Lines 1 to 3 in eefafad

  	[envs.default]
  	installer = "uv"
  	features = ["dev"]

• This allows to rely on standard metadata without allow-direct-references:

  anndata/pyproject.toml

  Line 67 in eefafad

  "towncrier>=24.8.0rc1",

[flying-sheep]

Some thoughts:

1. https://towncrier.readthedocs.io/en/stable/pre-commit.html
2. We can maybe simply use sections for our minor version headers:
   1. create directories release-notes/0.10 and release-notes/0.11
   2. create feature snippets in 0.11 and others in 0.10
   3. if we release a bugfix release, we stash the 0.11 directory and run towncrier, if we create a feature release, we move all snippets to the 0.11 directory and run towncrier.

[ilan-gold]

We can maybe simply use sections for our minor version headers:

Is there something wrong with our current system? I like the separate branches, like v0.10, which will contain fragments (after the the inital feature release) that aren't features so there's no need to stash or for separate directories etc.

[flying-sheep]

I like the separate branches, like v0.10, which will contain fragments (after the the inital feature release) that aren't features so there's no need to stash or for separate directories etc.

ah, sure, the bugfix branch doesn’t have the feature fragments, makes sense!

And actually we can’t use sections for what I was thinking.

My comment was about this structure:

when we do a feature release, we’d want to insert

(v0.11)=
## Version 0.11

before the new 0.11.0 version we’re creating.

and when we do a bugfix release, we want our new section to be inserted below the “Version 0.10” header.

There is only one insertion point: see here

but maybe moving that around as part of the release automation isn’t so bad!

[flying-sheep]

Ooof, now that I wrote all this code, I realized there’s an even better solution:

Replace the whole content of release-notes/index.md with

# Release notes

```{release-notes} .
```

and implement the release-notes directive that collects all *.*.*.{rst,md} file names in the directory . and constructs the whole doctree that file currently contains.

[flying-sheep]

TODO:

• migrate 0.11.0.md to feature fragments ((chore): v0.11 fragments #1611)
• backport everything except for feature fragments to 0.10.x branch (this PR has the milestone 0.10.9)

[ilan-gold]

@flying-sheep It will be easier to backport this if we simply don't do the 0.11 fragments on this branch. I will open up a follow-up PR.