feat: add release checklist #442
Conversation
Closes: #387 Ref: #384 (comment)
There was a problem hiding this comment.
Thanks for writing this up @rvagg! The big win here to me is that we're getting this documented so it can be iterated.
Some non-blocking thoughts:
- It seems like we have a decent amount of manual steps here in creating the changelog. I agree a human is needed to pull important thoughts out out though, especially for breaking changes or to highlight important new additions.
- I think the changelog / release notes themselves could likely benefit from some more headers/emojis (e.g., https://github.com/ipfs/go-ipfs/releases/tag/v0.13.0 ). Something like "Breaking Changes", "Notable Feeatures". Anyways, this process doesn't preclude that and it can be improved in the future if relevant.
That's why I'm recommending using changelog-maker to help craft it. I wrote that tool in 2015 to help better communicate changes in Node.js releases and it's since become a standard part of the process. It's helped by a formalised commit message scheme that can be pulled apart into sub-sections automatically, and some metadata that's now mandatory in each merged commit. I've done some updating of it (@ nodejs/changelog-maker#130) so it doesn't need the metadata on commits to match PRs so it can be used on any repo. With descriptive enough commits I think it should be fairly minimal work to group things together, remove extraneous ones and do a bit of renaming an highlighting to make a workable changelog entry. I've reduced the manual steps even more from the ones that Eric has previously taken and documented in #384 (comment), I think it's more manageable now. With better commit conventions it could be even better but one thing at a time, people get precious about their git conventions.
Oh, you're stretching me there with emojis ... But OK, I'll do the headers thing in #440 and come back and update this. |
rvagg
force-pushed
the
rvagg/release-checklist
branch
from
ecf04e7
to
986ed1f
Compare
|
Added 🤮 emojis and grouped the changes into two sections to highlight "breaking" changes in #440; updated the docs here to suggest that. |
|
@rvagg : it all looks good to me - thanks for moving this forward. That's great about changelog-maker. Concerning changelog organization, I think having headers is useful. Don't feel pressured in to using emojis because of me if that isn't the IPLD way. Thanks again for doing this Rod. |
|
|
||
| ## Checklist | ||
|
|
||
| Prior to opening a release proposal pull request, create an issue with the following markdown checklist to help ensure the requisite steps are taken. The issue can also be used to alert subscribed developers to the timeframe and the approximate scope of changes in the release. |
There was a problem hiding this comment.
Would it make sense to create a GH issue template for this?
There was a problem hiding this comment.
Yeah, I think that is smart to do and have it point back to this file.
Example of this being done in go-libp2p: https://github.com/libp2p/go-libp2p/blob/master/.github/ISSUE_TEMPLATE/release.md
There was a problem hiding this comment.
I don't really want to do this because we currently don't have any issue templates, so it introduces an extra step in the New Issue flow for everyone, just to support releases for one person.
If/when we start adding templates for other types of issues then we could add this one, otherwise it's going to be an extra "do you want to file an issue or make a release" in-between step for everyone.
There was a problem hiding this comment.
Yeah totally fair. Revisiting once there are other templates seems like a good idea. 😁
|
Going to punt on the issue template thread for further discussion and maybe implementation later; just not in this current version. |
Closes: #387
Ref: #384 (comment)
Putting into practice @ #440 for v0.17.0