Add RELEASE.md and CHANGELOG.md automation (#553)

This adds a RELEASE.md file that describes the release process in
detail, and also adds automation for updating the CHANGELOG in the
release workflow to reduce manual steps.

Now, the publish workflow will create two commits: one will update the
CHANGELOG, swapping out "Unreleased" for the new tag, and adding a new
"Unreleased" section above it. It commits those changes, then continues
on to `npm run package <version>`, which creates another commit, which
are both pushed directly to `main`.

Author: stefanvanburen

.github/workflows/publish.yaml

@@ -42,6 +42,9 @@ jobs:
           git config --global user.email "256439237+app-token-vscode-buf-release[bot]@users.noreply.github.com"
           git config --global user.name "app-token-vscode-buf-release[bot]"
           git config --global url."https://x-access-token:${{ steps.generate_gh_token.outputs.token }}@github.com/bufbuild/vscode-buf".insteadOf "https://github.com/bufbuild/vscode-buf"
+          make updatechangelog VERSION=${{ github.event.release.tag_name }}
+          git add CHANGELOG.md
+          git commit -m "Update CHANGELOG.md to version ${{ github.event.release.tag_name }}"
           npm run package ${{ github.event.release.tag_name }}
           git push https://x-access-token:${{ steps.generate_gh_token.outputs.token }}@github.com/${{ github.repository }}.git HEAD:${{ github.event.repository.default_branch }}
 
@@ -51,6 +54,9 @@ jobs:
           git config --global user.email "256439237+app-token-vscode-buf-release[bot]@users.noreply.github.com"
           git config --global user.name "app-token-vscode-buf-release[bot]"
           git config --global url."https://x-access-token:${{ steps.generate_gh_token.outputs.token }}@github.com/bufbuild/vscode-buf".insteadOf "https://github.com/bufbuild/vscode-buf"
+          make updatechangelog VERSION=${{ github.event.release.tag_name }}
+          git add CHANGELOG.md
+          git commit -m "Update CHANGELOG.md to version ${{ github.event.release.tag_name }}"
           npm run package:prerelease ${{ github.event.release.tag_name }}
           git push https://x-access-token:${{ steps.generate_gh_token.outputs.token }}@github.com/${{ github.repository }}.git HEAD:${{ github.event.repository.default_branch }}
 

Makefile

@@ -1,9 +1,34 @@
 .DEFAULT_GOAL := package
 
+UNAME_OS := $(shell uname -s)
+
+ifeq ($(UNAME_OS),Darwin)
+# Explicitly use the "BSD" sed shipped with Darwin. Otherwise if the user has a
+# different sed (such as gnu-sed) on their PATH this will fail in an opaque
+# manner. /usr/bin/sed can only be modified if SIP is disabled, so this should
+# be relatively safe.
+SED_I := /usr/bin/sed -i ''
+endif
+ifeq ($(UNAME_OS),Linux)
+SED_I := sed -i
+endif
+
+
 .PHONY: package
 package:
 	npm run package
 
 .PHONY: install
 install:
 	npm install
+
+# This target is used in ./.github/workflows/publish.yaml;
+# do not change it without updating the callsite there.
+.PHONY: updatechangelog
+updatechangelog:
+ifndef VERSION
+	$(error VERSION is required. Usage: make updatechangelog VERSION=1.0.0)
+endif
+	@echo "Updating CHANGELOG.md with version $(VERSION)..."
+	$(SED_I) 's/^## Unreleased$$/## Unreleased\n\n## $(VERSION)/' CHANGELOG.md
+	@echo "Done! CHANGELOG.md updated."

RELEASE.md

@@ -0,0 +1,25 @@
+# Releasing vscode-buf
+
+This document outlines how to create a release of vscode-buf.
+
+The VS Code extension is published to both [Microsoft’s Visual Studio Marketplace](https://marketplace.visualstudio.com/items?itemName=bufbuild.vscode-buf) and [Open VSX](https://open-vsx.org/extension/bufbuild/vscode-buf).
+
+1. Make sure all dependencies are upgraded, and that CI on `main` is green.
+
+2. Ensure the [CHANGELOG](./CHANGELOG.md) reflects the state of the world;
+   look through the commits between now and the latest release to ensure all user-facing changes are reflected.
+
+3. Using the GitHub UI, create a new release.
+   - Under “Choose a tag”, type in “X.Y.Z” to create a new tag for the release upon publish.
+     - _Important_: Do not include a "v" prefix on the version.
+     - _Important_: VS Code Marketplace requires a non-prerelease semver version (e.g., `1.0.0-rc1` is disallowed).
+       Use a non-prerelease semver version even if you plan to tick the "set as a pre-release" box.
+   - Target the main branch.
+   - Title the Release “X.Y.Z”.
+   - Click “set as latest release”.
+   - Set the last version as the “Previous tag”.
+   - Copy in the release notes from the CHANGELOG.md "Unreleased" section.
+     - If any edits need to be made, you can save the release as a draft, make a PR to edit the CHANGELOG, and then copy in the new changes.
+
+4. Publish the release.
+   The ["Publish Extension" workflow](./.github/workflows/publish.yaml) will take care of updating the CHANGELOG and package.json to the given version.