From 6b9d7bf1c6a184d87b39175d67960612acd96162 Mon Sep 17 00:00:00 2001 From: Rod Vagg Date: Wed, 15 Jun 2022 19:10:03 +1000 Subject: [PATCH 1/4] feat: add release checklist Closes: https://github.com/ipld/go-ipld-prime/issues/387 Ref: https://github.com/ipld/go-ipld-prime/issues/384#issuecomment-1061964620 --- HACKME_releases.md | 69 ++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 69 insertions(+) create mode 100644 HACKME_releases.md 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 +``` From d8445e5c9c9cf9e882573c902bc631a9ca9b8084 Mon Sep 17 00:00:00 2001 From: Rod Vagg Date: Thu, 16 Jun 2022 13:28:05 +1000 Subject: [PATCH 2/4] fixup! feat: add release checklist --- HACKME_releases.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/HACKME_releases.md b/HACKME_releases.md index c019e4bb..eb6602b1 100644 --- a/HACKME_releases.md +++ b/HACKME_releases.md @@ -54,7 +54,7 @@ Optional: Protocol Labs staff can send an email to shipped@protocol.ai to descri ## Checklist -A release proposal pull request may use the following markdown checklist to help ensure the requisite steps are taken: +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. ```markdown * [ ] Add new h3 to `CHANGELOG.md` under **Released Changes** with curated list of changes and links to relevant PRs From 986ed1f406da1e9a21f26fc5d1c99959eede5bd0 Mon Sep 17 00:00:00 2001 From: Rod Vagg Date: Thu, 16 Jun 2022 17:26:14 +1000 Subject: [PATCH 3/4] fixup! feat: add release checklist --- HACKME_releases.md | 20 ++++++++++---------- 1 file changed, 10 insertions(+), 10 deletions(-) diff --git a/HACKME_releases.md b/HACKME_releases.md index eb6602b1..e6eab4bc 100644 --- a/HACKME_releases.md +++ b/HACKME_releases.md @@ -8,28 +8,28 @@ go-ipld-prime follows **[WarpVer](https://gist.github.com/warpfork/98d2f4060c68a 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.: +To find the list of commits, it is recommended that you 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): ``` -git log --all --graph --date-order --abbrev-commit --decorate --oneline +npx changelog-maker --start-ref=v0.16.0 --reverse=true --find-matching-prs=true --md=true ipld go-ipld-prime ``` -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): +Alternatively, you can use `git log` and perform mapping to pull requests manually, e.g.: ``` -npx changelog-maker --start-ref=v0.16.0 --reverse=true --find-matching-prs=true --md=true ipld go-ipld-prime +git log --all --graph --date-order --abbrev-commit --decorate --oneline ``` *(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. +1. Group commits to subsystem to create a two-level list. Subsections can include "Data Model", "Schemas", "Bindnode", "Selectors", "Codecs", and the meta-category of "Build" to describe changes local to the repository and not necessarily relevant to API consumers. +2. If there are breaking, or potentially breaking changes, list them under a `### 🛠 Breaking Changes` section. +3. Otherwise, prune the list of commits down to the set of changes relevant to users, and list them under a `### 🔦 Highlights` section. + 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 @@ -57,8 +57,8 @@ Optional: Protocol Labs staff can send an email to shipped@protocol.ai to descri 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. ```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 new h3 to `CHANGELOG.md` under **Released Changes** with curated and subsystem-grouped list of changes and links to relevant PRs + * [ ] Highlight any potentially breaking or disruptive changes under "🛠 Breaking Changes", including extended descriptions to help users make compatibility judgements * [ ] 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` From 322f713826dc463aac0e4c677717ec41352c7aad Mon Sep 17 00:00:00 2001 From: Rod Vagg Date: Fri, 17 Jun 2022 11:38:18 +1000 Subject: [PATCH 4/4] fixup! feat: add release checklist --- HACKME_releases.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/HACKME_releases.md b/HACKME_releases.md index e6eab4bc..b67097b2 100644 --- a/HACKME_releases.md +++ b/HACKME_releases.md @@ -27,8 +27,8 @@ git log --all --graph --date-order --abbrev-commit --decorate --oneline 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. 1. Group commits to subsystem to create a two-level list. Subsections can include "Data Model", "Schemas", "Bindnode", "Selectors", "Codecs", and the meta-category of "Build" to describe changes local to the repository and not necessarily relevant to API consumers. -2. If there are breaking, or potentially breaking changes, list them under a `### 🛠 Breaking Changes` section. -3. Otherwise, prune the list of commits down to the set of changes relevant to users, and list them under a `### 🔦 Highlights` section. +2. If there are breaking, or potentially breaking changes, list them under a `#### 🛠 Breaking Changes` section. +3. Otherwise, prune the list of commits down to the set of changes relevant to users, and list them under a `#### 🔦 Highlights` section. 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.