diff --git a/HACKME_releases.md b/HACKME_releases.md new file mode 100644 index 00000000..c019e4bb --- /dev/null +++ b/HACKME_releases.md @@ -0,0 +1,69 @@ +# Making go-ipld-prime Releases + +## Versioning strategy + +go-ipld-prime follows **[WarpVer](https://gist.github.com/warpfork/98d2f4060c68a565e8ad18ea4814c25f)**, a form of SemVer that never bumps the major version number and uses minor version numbers to indicate degree of *changeness*: **even numbers should be easy upgrades; odd numbers may change things**. The patch version number is rarely used in this scheme. + +## CHANGELOG.md + +There is a CHANGELOG.md, it should be relevant and updated. Notable items in the commit history since the last release should be included. Where possible and practical, links to relevant pull requests or other issues with discussions on the items should be included. + +Finding the list of commits can be done using `git log`, e.g.: + +``` +git log --all --graph --date-order --abbrev-commit --decorate --oneline +``` + +Matching commits to pull requests may be a manual process with this method. + +Alternatively, use a tool that can provide some extra metadata to help with matching commits to pull requests. [changelog-maker](https://github.com/nodejs/changelog-maker) can help with this (requires Node.js be installed and the `npx` command be available): + +``` +npx changelog-maker --start-ref=v0.16.0 --reverse=true --find-matching-prs=true --md=true ipld go-ipld-prime +``` + +*(where `--start-ref` points to name of the previous release tag)* + +### Curate and summarize + +The output of a git log can be a helpful starting point for developing a CHANGELOG.md entry, but is unlikely to be an ideal final form as commit messages are rarely informative enough and multiple commits may be associated with a single PR / change. + +The CHANGELOG should be informative for developers wanting to know what changes may pose a risk (highlight these!) and what changes introduce features they may be interested in using. + +Note that there is also a **Planned/Upcoming Changes** section near the top of the CHANGELOG.md. Update this to remove _done_ items and add other items that may be nearing completion but not yet released. + +### Call-outs + +Add "special thanks" call-outs to individuals who have contributed meaningful changes to the release. + +## Propose a release + +After updating the CHANGELOG.md entry, also bump the version number appropriately in **version.json** file so the auto-release procedure can take care of tagging for you. + +Commit and propose the changes via a pull request to ipld/go-ipld-prime. + +## Release + +After a reasonable amount of time for feedback (usually at least a full global business day), the changes can be merged and a release tag will be created by the GitHub Actions. + +Use the GitHub UI to make a [release](https://github.com/ipld/go-ipld-prime/releases), copying in the contents of the CHANGELOG.md for that release. + +Drop in a note to the appropriate Matrix/Discord/Slack channel(s) for IPLD about the release. + +Optional: Protocol Labs staff can send an email to shipped@protocol.ai to describe the release, these are typically well-read and appreciated. + +## Checklist + +A release proposal pull request may use the following markdown checklist to help ensure the requisite steps are taken: + +```markdown +* [ ] Add new h3 to `CHANGELOG.md` under **Released Changes** with curated list of changes and links to relevant PRs + * [ ] Highlight any potentially breaking or disruptive changes + * [ ] Add special-thanks call-outs to contributors making significant contributions +* [ ] Update **Planned/Upcoming Changes** section to remove completed items and add newly upcoming, but incomplete items +* [ ] Bump version number appropriately in `version.json` +* [ ] Propose release via pull request, merge after enough time for async global feedback +* [ ] Create GitHub [release](https://github.com/ipld/go-ipld-prime/releases) with the new tag, copying the new `CHANGELOG.md` contents +* [ ] Announce on relevant Discord/Matrix/Slack channel(s) +* [ ] (Optional) Announce to shipped@protocol.ai +```