Skip to content
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

MAINT: Improve changelog documentation process #11508

Closed
larsoner opened this issue Feb 24, 2023 · 9 comments · Fixed by #12299
Closed

MAINT: Improve changelog documentation process #11508

larsoner opened this issue Feb 24, 2023 · 9 comments · Fixed by #12299
Assignees

Comments

@larsoner
Copy link
Member

To aid in releases and PRs, it would be nice not to have to do so much changelog management. In particular, it would be great if:

  1. We didn't have to tell people to add anything to doc/changes/latest.inc
  2. A changelog could be (at least nearly) automatically generated

Ideas:

  • In sphinx-gallery we use github-changelog-generator in between releases. You label PRs (before or after merge!) to get them correctly categorized as enhancement/bug. I think you can even change the PR title after the merge to then have that text used in the changelog entry.

Clearly this list is incomplete :) @drammock or others feel free to add other ideas up here after commenting about them below

@larsoner
Copy link
Member Author

... and as part of this, we should abandon any further updates to names.inc. We can keep it for posterity / our old logs, but for the future we should use some automated tool to get the change -> GH user link, which then gets us their name (contributors should keep their GH profile up to date, if they don't, then they just get their handle as their name, which I think is okay) and we just link to their GH profile -- where they can keep and update their own URLs.

@agramfort
Copy link
Member

agramfort commented Feb 25, 2023 via email

@larsoner
Copy link
Member Author

At least github-changelog-generator we've already used in SG for years now. But yes if we want to try something else then we could experiment elsewhere in principle.

But in practice I think you try the tool and see if it produces some usable RST or not, so it would be easy to evaluate in a PR I think....

@agramfort
Copy link
Member

agramfort commented Feb 25, 2023 via email

@sappelhoff
Copy link
Member

I think you can even change the PR title after the merge to then have that text used in the changelog entry.

yes, and you can also define a certain GitHub label to explicitly exclude a PR / issue from the changelog, see e.g.:

https://github.com/bids-standard/bids-specification/blob/5d749397c50d33a498c629c279171667f439fae7/.circleci/config.yml#L123

@larsoner
Copy link
Member Author

FWIW I just went through the process with sphinx-gallery and this is the result:

https://sphinx-gallery.github.io/stable/changes.html#v0-12-0

label->section mapping is configurable. It still involves a few steps but in general it's faster and I think I'd prefer it to what we have now.

Ahead of our next release I could try running it on our repo for 1.4 and we could see the result. I don't think it would take too much time for me to mock it up at least.

@drammock
Copy link
Member

another candidates:

@larsoner
Copy link
Member Author

larsoner commented Oct 2, 2023

Tentative plan from discussion with @agramfort and @drammock :

  1. Continue using devel.rst for 1.6 release (i.e., ~1 month)
  2. Use github_changelog_generator for the 1.7 release, meaning we no longer change devel.rst with every change

In the next month, I can try github_changelog_generator to see what it would have produced for 1.6 so we can iterate on that process ahead of time to make sure it's tractable.

@larsoner
Copy link
Member Author

@drammock thinking about this again, I'm starting to think towncrier might make sense:

  1. Used by astropy etc. so we're not alone or blazing a new trail
  2. There is an action to make sure there is a fragment which will help maintenance
  3. Customizable sections will allow us to easily address DOC: Update changelog sections #12233

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