From 0fdb9aa9e226dab3bb06dc3535f2f4c4879dbba0 Mon Sep 17 00:00:00 2001
From: metonym <ericyl.us@gmail.com>
Date: Sun, 12 Nov 2023 14:25:37 -0800
Subject: [PATCH] docs: update CONTRIBUTING.md (#1842)

---
 CONTRIBUTING.md | 47 ++++++++++++++++++++++++++++++++---------------
 package.json    |  3 +--
 2 files changed, 33 insertions(+), 17 deletions(-)

diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index befc6bb8..e82d4f2f 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -165,27 +165,44 @@ The following items only apply to project maintainers.
 
 ### Release
 
+This library is published to NPM with [provenance](https://docs.npmjs.com/generating-provenance-statements) via a [GitHub workflow](https://github.com/carbon-design-system/carbon-components-svelte/blob/master/.github/workflows/release.yml).
+
+The workflow is automatically triggered when pushing a tag that begins with `v` (e.g., `v0.81.1`).
+
+However, maintainers must perform a few things in preparation for a release.
+
 Locally, while on `master` and the branch is clean, run `yarn release`. This command will:
 
-- Build library and docs
-- Bump package.json version
-- Add notes to Changelog
+- Bump the semantic version in `package.json`
+- Generate notes in `CHANGELOG.md`
+- Run `yarn build:docs` to update the generated documentation
 
 This command will not create a commit nor tag. Afterwards, perform the following manually:
 
 ```sh
-# 1. Stage prepared files for a commit
-git add .
+# 1. Commit the changes using the new version as the commit message.
+git commit -am "v0.81.1"
 
-# 2. Commit based on the current version, either manually or with jq
-git commit -m "v$(jq -r '.version' package.json)"
+# 2. Create a tag.
+git tag v0.81.1
 
-# 3. Create a tag based on the current version, either manually or with `jq`:
-git tag "v$(jq -r '.version' package.json)"
-
-# 4. Push branch and tag, then publish
-git push origin master [tag]
-yarn publish
-
-# 5. Generate release notes on GitHub, and comment on issues and pull requests
+# 3. Push the tag to the remote.
+# This will trigger the `release.yml` workflow to publish a new package to NPM (with provenance).
+git push origin v0.81.1
+```
+
+If all goes as expected, the [`release.yml` workflow](https://github.com/carbon-design-system/carbon-components-svelte/actions/workflows/release.yml) should trigger a new run and publish the new version to NPM.
+
+### Post-release checklist
+
+After confirming that the new release is published to NPM, perform the following:
+
+1. Create a [new release](https://github.com/carbon-design-system/carbon-components-svelte/releases/new) on GitHub. Click "Generate release notes" to automatically list changes by commit with the relevant Pull Request and author metadata. You may manually remove notes that are not relevant to the release (e.g., CI changes).
+
+2. Publish the release as the latest release.
+
+3. As good practice, visit the Pull Request and/or issue for each commit and manually confirm that it's been released. This is helpful for future readers to understand what version includes the new feature or fix.
+
+```md
+Released in [v0.81.1](https://github.com/carbon-design-system/carbon-components-svelte/releases/tag/v0.81.1).
 ```
diff --git a/package.json b/package.json
index 3a0665a7..6f08e054 100644
--- a/package.json
+++ b/package.json
@@ -17,8 +17,7 @@
     "build:docs": "node scripts/build-docs",
     "build:lib": "rollup -c",
     "format": "prettier --write \"./**/*.{svelte,js,md}\"",
-    "prepack": "yarn build:docs & yarn build:lib",
-    "release": "standard-version && yarn prepack"
+    "release": "standard-version && yarn build:docs"
   },
   "dependencies": {
     "flatpickr": "4.6.9"