Generate changelogs from fragements

zarr-developers / zarr-python

An implementation of chunked, compressed, N-dimensional arrays for Python.

https://zarr.readthedocs.io

MIT License

1.51k stars 278 forks source link

Generate changelogs from fragements #829

Open joshmoore opened 3 years ago

joshmoore commented 3 years ago

e.g. https://github.com/ansible-community/antsibull-changelog/blob/main/docs/other-projects.rst

At the moment, PRs regularly conflict due to conflicts to release.rst. By moving to a fragment based system, this should go away.

Any other recommendations for frameworks?

grlee77 commented 3 years ago

Towncrier is used by NumPy and we are considering it for scikit-image

joshmoore commented 3 years ago

Had looked at that one previously as well. :+1: All the better if your experiences have been good.

grlee77 commented 3 years ago

We have a draft PR and were planning to start using it in the near future, so I don't have much experience with it yet. I was not aware of the ansible one you linked above, but it sounds like something similar.

Another approach that SciPy has used in the past is having contributors update a wiki page that the release manager can then pull from when making the release notes. I'm not sure how consistently it is applied, though.

Towncrier or antsibull will solve the conflicts problem, but there is still the separate problem of prompting contributors to create the fragments needed!

joshmoore commented 3 years ago

I'd hope it'd be easy enough to add an action that says, "must have fragment". Worst case: we can push it to the PRs manually. :wink:

joshmoore commented 2 years ago

Another possible option: https://sphinx-github-changelog.readthedocs.io/en/latest/ (...as I struggle with the anchors for pre-releases ...)

cc: @MSanKeys963

joshmoore commented 2 years ago

@jakirkham suggests https://github.com/regro/rever
@alimanfoo suggests looking at how dask does it.

But generally, :+1: for:

keeping it simple
having a check on all PRs
ability to break the current formatting & move to something new (e.g. with zarr-python 3.x)

jakirkham commented 2 years ago

We've used rever in conda-smithy

jakirkham commented 2 years ago

Josh mentioned this changelog proposal.

jakirkham commented 2 years ago

Another option somewhat similar to towncrier is scriv

joshmoore commented 2 years ago

@MSanKeys963: this is something to review before we (potentially) launch the outreachy project.

MSanKeys963 commented 2 years ago

Sure. Adding to the list. We can let the Outreachy intern experiment with multiple tools before we finalise a single one for Zarr.

jakirkham commented 2 years ago

+1 though it would be good to make sure that those experimenting get credit for that (even if it doesn't wind up merged). The experimenting is itself a useful step 🙂