search

asdf-format / asdf

ASDF (Advanced Scientific Data Format) is a next generation interchange format for scientific data
http://asdf.readthedocs.io/
BSD 3-Clause "New" or "Revised" License
523 stars 57 forks source link

handle changelog entries with `towncrier` #1826

Closed zacharyburnett closed 1 month ago

zacharyburnett commented 1 month ago

Description

towncrier expects "news fragment" files (text files in the changes/ directory with filenames in the format <PR#>.<changetype>.rst, i.e. for this PR it would be changes/1826.misc.rst). See docs at https://towncrier.readthedocs.io/en/latest/tutorial.html#creating-news-fragments

when ready to make a release, run towncrier build to ingest the news fragments and generate a changelog section in CHANGES.rst with all the new change log entries for that release (this clears the changes/ directory). This step should either be done before making a release, or could probably be added to a GitHub workflow triggered on release (to insert a commit and remake the tag).

After merging this PR the Release Process wiki page will need to be updated to include a step to run towncrier and add to CHANGES.rst.

Currently this PR uses the default towncrier change types:

However, you can also define custom types; I think it might be easier for users to use the above sections in the changelog instead of what we currently use (more or less one section per-module). I can add those sections back though, if that's better

Checklist:

braingram commented 1 month ago

How could we update our changelog check to use the new format? I see the changelog-bot configuration in this PR do we have to enable that bot? If so, is there a way that doesn't require another bot (like an action that uses towncrier check?

Also, for the "running changelog" I'm thinking one option might be to add a towncrier build --draft and redirect it's output to the action summary for the nightly cron job. Are there other options that might be useful here to be able to get a (reasonably up-to-date) running changelog for what will go into the next build?

zacharyburnett commented 1 month ago

How could we update our changelog check to use the new format? I see the changelog-bot configuration in this PR do we have to enable that bot? If so, is there a way that doesn't require another bot (like an action that uses towncrier check?

towncrier check seems to do this, by doing a very simple check for if a new file has been added by the current branch in changes/ (this current branch passes that check because of changes/.gitkeep)

Also, for the "running changelog" I'm thinking one option might be to add a towncrier build --draft and redirect it's output to the action summary for the nightly cron job. Are there other options that might be useful here to be able to get a (reasonably up-to-date) running changelog for what will go into the next build?

I think this might be unnecessary, as anyone can run towncrier build --draft locally if they need it (it would be just as much effort as checking the run summaries)

braingram commented 1 month ago

Is there a way to tell towncrier to check for a fragment for a particular PR number? Let's say we open a PR 1900 with some feature. Is there a way to check that a 1900.<something>.rst exists and not say 19000.<something>.rst?

zacharyburnett commented 1 month ago

Is there a way to tell towncrier to check for a fragment for a particular PR number? Let's say we open a PR 1900 with some feature. Is there a way to check that a 1900.<something>.rst exists and not say 19000.<something>.rst?

the docs aren't clear: https://towncrier.readthedocs.io/en/stable/cli.html#towncrier-check

I'll test with another test branch

zacharyburnett commented 1 month ago

I don't see how it would have a way to know the PR number; I think that's why the changelog bot is used.

❯ towncrier check --compare-with changelog/towncrier
Looking at these files:
----
1. /Users/zburnett/projects/asdf/README.rst
----
No new newsfragments found on this branch.
❯ touch changes/2122.misc.rst
❯ towncrier check --compare-with changelog/towncrier
Looking at these files:
----
1. /Users/zburnett/projects/asdf/README.rst
2. /Users/zburnett/projects/asdf/changes/2122.misc.rst
----
Found:
1. /Users/zburnett/projects/asdf/changes/2122.misc.rst
braingram commented 1 month ago

I don't see how it would have a way to know the PR number; I think that's why the changelog bot is used.

Thanks for checking. I guess we could re-introduce the regex and update it to check either the output of towncrier build --draft or for a file <PR number>.<something>.rst. It seems like an important feature to keep and I'm hesitant to enable another bot.

Also, do you have a suggestion for our docs? They list the changelog contents: https://github.com/asdf-format/asdf/blob/dbbc26f5f0c3a4a7775bca0903bd0051a132b2e4/docs/asdf/changes.rst?plain=1#L7 and I can see a benefit to generating a "draft" changelog for PR docs builds (to make sure the added changelog doesn't cause a sphinx error on release).

zacharyburnett commented 1 month ago

we could add towncrier build to the changelog checker after checkout, and also the readthedocs run

zacharyburnett commented 1 month ago

@braingram good idea! https://asdf--1826.org.readthedocs.build/en/1826/asdf/changes.html

braingram commented 1 month ago

I think the regex isn't quite right: https://github.com/asdf-format/asdf/actions/runs/10460294667/job/28966161889?pr=1825 and the docs are failing to build with a fragment (it looks to be waiting for user input): https://readthedocs.org/projects/asdf/builds/25358714/

zacharyburnett commented 1 month ago

I think the regex isn't quite right: https://github.com/asdf-format/asdf/actions/runs/10460294667/job/28966161889?pr=1825

fixed in #1828

and the docs are failing to build with a fragment (it looks to be waiting for user input): https://readthedocs.org/projects/asdf/builds/25358714/

~I'll take a look~ fixed in #1829