Setup Changesets

.changeset/README.md

@@ -0,0 +1,8 @@
+# Changesets
+
+Hello and welcome! This folder has been automatically generated by `@changesets/cli`, a build tool that works
+with multi-package repos, or single-package repos to help you version and publish your code. You can
+find the full documentation for it [in our repository](https://github.com/changesets/changesets)
+
+We have a quick list of common questions to get you started engaging with this project in
+[our documentation](https://github.com/changesets/changesets/blob/main/docs/common-questions.md)

.changeset/config.json

@@ -0,0 +1,17 @@
+{
+    "$schema": "https://unpkg.com/@changesets/[email protected]/schema.json",
+    "changelog": [
+        "@changesets/changelog-github",
+        {
+            "repo": "TBD54566975/web5-js"
+        }
+    ],
+    "commit": false,
+    "fixed": [],
+    "linked": [],
+    "access": "public",
+    "baseBranch": "main",
+    "updateInternalDependencies": "patch",
+    "bumpVersionsWithWorkspaceProtocolOnly": true,
+    "ignore": []
+}

.github/workflows/docs-publish.yml

@@ -5,11 +5,8 @@ on:
   # Allows you to run this workflow manually from the Actions tab
   workflow_dispatch:
 
-  # Automatically triggers when a new release is published
-  workflow_run:
-    workflows: ["Release to NPM Registry"]
-    types:
-      - completed
+  # Call from the release workflow
+  workflow_call:
 
 # Allow only one concurrent deployment, skipping runs queued between the run in-progress and latest queued.
 # However, do NOT cancel in-progress runs as we want to allow these production deployments to complete.

.github/workflows/release.yml

@@ -0,0 +1,122 @@
+name: Release
+
+on:
+  push:
+    branches:
+      - main
+
+  # Allows you to run this workflow manually from the Actions tab
+  workflow_dispatch:
+    inputs:
+      initiate_api_release:
+        description: "Initiate @web5/api release"
+        required: false
+        default: false
+        type: boolean
+
+  # Triggered when a PR is labeled/unlabeled with `api-release`
+  pull_request_target:
+    types: [labeled, unlabeled]
+    branches:
+      - main
+
+concurrency: ${{ github.workflow }}-${{ github.ref }}
+
+jobs:
+  release:
+    # if not a fork, and its a pr label event, check if the head ref is a release branch
+    if: github.repository == 'TBD54566975/web5-js' && (github.event_name != 'pull_request_target' || (contains(github.event.action, 'labeled') && startsWith(github.event.pull_request.head.ref, 'changeset')))
+
+    permissions:
+      contents: write # to create release (changesets/action)
+      pull-requests: write # to create pull request (changesets/action)
+      id-token: write # necessary for NPM provenance
+
+    name: Release
+    runs-on: ubuntu-latest
+
+    outputs:
+      published: ${{ steps.changesets.outputs.published }}
+
+    steps:
+      - name: Checkout source
+        uses: actions/checkout@b4ffde65f46336ab88eb53be808477a3936bae11 #v4.1.1
+        with:
+          ref: main
+
+      # https://cashapp.github.io/hermit/usage/ci/
+      - name: Init Hermit
+        uses: cashapp/activate-hermit@31ce88b17a84941bb1b782f1b7b317856addf286 # v1.1.0
+        with:
+          cache: "true"
+
+      - name: Store NPM Registry Settings to .npmrc
+        run: |
+          echo -e "//registry.npmjs.org/:_authToken=\${NODE_AUTH_TOKEN}" > ~/.npmrc
+
+      - name: Verify NPM token is authenticated with NPMjs.com
+        env:
+          NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}
+        run: pnpm whoami
+
+      - name: Install dependencies
+        run: pnpm install --frozen-lockfile
+
+      - name: Build all workspace packages
+        env:
+          NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}
+        run: pnpm --recursive --stream build
+
+      - name: Check @web5/api Release Flow
+        id: check_api_release
+        run: scripts/changesets-api-release-check.sh
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+          KICK_API_RELEASE: ${{ github.event.inputs.initiate_api_release || '' }}
+
+      - name: Create Release Pull Request or Publish to npm
+        uses: changesets/action@aba318e9165b45b7948c60273e0b72fce0a64eb9 # v1.4.7
+        id: changesets
+        if: steps.check_api_release.outputs.skip_release != 'true'
+        with:
+          publish: pnpm changeset publish
+          version: scripts/changesets-version.sh ${{ steps.check_api_release.outputs.release_web5_api || '' }}
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+          NPM_TOKEN: ${{ secrets.NPM_TOKEN }}
+          NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}
+
+      - name: Label Changesets PR with API release
+        if: github.event.inputs.initiate_api_release && steps.changesets.outputs.pullRequestNumber != ''
+        uses: actions/github-script@60a0d83039c74a4aee543508d2ffcb1c3799cdea # v7.0.1
+        with:
+          script: |
+            github.rest.issues.addLabels({
+              issue_number: ${{ steps.changesets.outputs.pullRequestNumber }},
+              owner: context.repo.owner,
+              repo: context.repo.repo,
+              labels: ['api-release']
+            })
+
+      - name: Publish `next` preview
+        if: steps.changesets.outputs.published != 'true' && steps.changesets.outputs.pullRequestNumber != '' && steps.changesets.outputs.hasChangesets == 'true'
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+          NPM_TOKEN: ${{ secrets.NPM_TOKEN }}
+          NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}
+        run: |
+          git checkout main
+          SHORT_SHA=$(git rev-parse --short HEAD)
+          pnpm changeset version --snapshot next-$SHORT_SHA
+          pnpm changeset publish --no-git-tag --tag next
+
+  publish-docs:
+    permissions:
+      contents: write
+      pages: write
+      id-token: write
+
+    needs: release
+    name: Publish Docs
+    if: ${{ needs.release.outputs.published == 'true' }}
+    uses: ./.github/workflows/docs-publish.yml

CONTRIBUTING.md

@@ -51,13 +51,14 @@ Build and Test cycles are run on every commit to every branch using [GitHub Acti
 ## Development Prerequisites
 
 ### Hermit
+
 This project uses hermit to manage tooling like node. See [this page](https://cashapp.github.io/hermit/usage/get-started/) to set up Hermit on your machine - make sure to download the open source build and activate it for the project.
 
 Currently, we have these packages installed via Hermit (can also view by checking out `hermit status`):
 
-| Requirement | Tested Version | 
-| ----------- | -------------- | 
-| Node.js     | 20.9.0        | 
+| Requirement | Tested Version |
+| ----------- | -------------- |
+| Node.js     | 20.9.0         |
 | PNPM        | 8.15.4         |
 
 ### TypeScript
@@ -103,6 +104,7 @@ to your valuable work:
 
 > [!IMPORTANT]
 > Before running tests ensure you've completed the following steps:
+>
 > 1. Install the [development prerequisites](#development-prerequisites).
 > 2. Follow the [these steps](https://github.com/TBD54566975/web5-js#cloning) to clone this repository and `cd` into the project directory.
 > 3. Install all project dependencies by running `pnpm install` from the root directory of the project.
@@ -163,37 +165,80 @@ remains consistent and well-organized.
 #### Stable Releases
 
 We use semantic versioning for stable releases that have completed testing and are considered reliable enough for
-general use. Project maintainers will follow the steps below to create a new release:
+general use.
 
-1. For each updated package that requires a new release, update the version in `package.json` according to semantic versioning rules (`MAJOR.MINOR.PATCH`).
+This project uses [Changesets](https://github.com/changesets/changesets) for semver management. For motivations, see [full explanation here](https://github.com/changesets/changesets/blob/main/docs/detailed-explanation.md).
 
-1. In a local feature branch, commit the changes:
+Upon opening a Pull Request, the `changeset-bot` will automatically comment ([example](https://github.com/TBD54566975/tbdex-js/pull/30#issuecomment-1732721942)) on the PR with a reminder & recommendations for managing the changeset for the given changes.
 
-   ```
-   git add package.json
-   git commit -m "Bump version to x.y.z"
-   ```
+Prior to merging your branch into main, and given you have relevant semantic versioning changes, then you should run `npx changeset` locally.
 
-1. Create a tag for the new release:
+The CLI tool will walk you through a set of steps for you to define the semantic changes. This will create a randomly-named (and funnily-named) markdown file within the `.changeset/` directory. For example, see the `.changeset/sixty-tables-cheat.md` file on [this PR](https://github.com/TBD54566975/tbdex-js/pull/35/files). There is an analogy to staging a commit (using `git add`) for these markdown files, in that, they exist so that the developer can codify the semantic changes made but they don't actually update the semantic version.
 
-   ```
-   git tag -a vx.y.z -m "Release x.y.z"
-   ```
+**You can stop here!** It is recommended to merge your branch into main with the `.changeset/*.md` files, at which point, the Changeset GitHub Action will automatically pick up those changes and open a PR to automate the `npx changeset version` execution. For example, [see this PR](https://github.com/TBD54566975/tbdex-js/pull/36). This command will do two things: update the version numbers in the relevant `package.json` files & also aggregate Summary notes into the relevant `CHANGELOG.md` files. In keeping with the staged commit analogy, this is akin to the actual commit.
 
-1. Push the changes and the tag to the remote repository:
+**Publishing Releases**
 
-   ```
-   git push --tags
-   ```
+Project maintainers will just merge the [Version Packages PR](https://github.com/TBD54566975/web5-js/pulls?q=is%3Apr+author%3Aapp%2Fgithub-actions+%22Version+Packages%22+) when it's ready to publish the new versions!
 
-1. Open a pull request (PR) from your feature branch to begin the review process.
+When these PRs are merged to main we will automatically publish to NPM and create corresponding git tags with the changelog notes, and mirror each tag to a GitHub release per package.
 
-After one or more PRs have been approved and merged by project maintainers, a GitHub Release will be created using the
-version tag. The act of creating the GitHub release triggers automated publication of the package to the
-[NPM Registry](https://npmjs.com) which will be tagged as _latest_.
+> [!NOTE]
+>
+> This is all achieved by the Changesets GitHub action being used in the [Release Workflow](./.github/workflows/release.yml).
 
 The next time someone runs `pnpm install @web5/<package_name>` the newly published release will be installed.
 
+##### Recapping the steps for a new release publish
+
+Recap of the above changesets, plus the release process:
+
+1. Open a PR
+2. `changeset-bot` will automatically [comment on the PR](https://github.com/TBD54566975/tbdex-js/pull/30#issuecomment-1732721942) with a reminder & recommendations for semver
+3. Run `pnpm changeset` locally and push changes (`.changeset/*.md`)
+4. Merge PR into `main`
+5. Profit from the automated release pipeline:
+   - [Release Workflow](./.github/workflows/release.yml) will create a new Version Package PR, or update the existing one
+   - When maintainers are ready to publish the new changes, they will merge that PR and the very same [Release Workflow](./.github/workflows/release.yml) will automatically publish a [new version to NPM](https://www.npmjs.com/package/@web5/dids?activeTab=versions), and publish the docs to https://tbd54566975.github.io/web5-js/
+
+#### Web5 API Releases
+
+The `@web5/api` package is special because it dictates our release train schedule. Whenever a new Web5 API needs to be released projects maintainers will need to reach out to DevRel team to orchestrate an announcement to the community and follow a set of tests to ensure the Web5 API release is reliable and working ([example here](https://github.com/TBD54566975/developer.tbd.website/issues/1129)).
+
+**Because of that, the changesets of the `@web5/api` are ignored by default.**
+
+Check below how to enable the `@web5/api` package release.
+
+##### @web5/api New Standalone Release
+
+1. Go to the [Release workflow](https://github.com/TBD54566975/web5-js/actions/workflows/release.yml)
+2. Press the `Run Workflow` button and select the `Initiate @web5/api release` checkbox
+3. Push `Run Workflow`
+
+This will create a new [Version Packages PR](https://github.com/TBD54566975/tbdex-js/pulls?q=is%3Apr+author%3Aapp%2Fgithub-actions+%22Version+Packages%22+is%3Aopen) with the `@web5/api` package bump, if there are any relevant changesets for the package.
+
+##### @web5/api Release with other package bumps
+
+In the rare occasion where `@web5/api` needs to be bumped together with other packages, just label the existing Version Package PR.
+
+1. Go to the current [Version Packages PR](https://github.com/TBD54566975/tbdex-js/pulls?q=is%3Apr+author%3Aapp%2Fgithub-actions+%22Version+Packages%22+is%3Aopen)
+2. Label the PR with the `api-release` tag
+3. The release workflow should be triggered and the `@web5/api` package changes should be included in the PR as soon as the workflow completes.
+
+##### @web5/api Canceling Release
+
+If for some reason you need to bump other packages and the `@web5/api` is added to the current Version Package PR, this will probably block your release until everything is sorted in the web5/dwn side of things... Follow the steps below to ignore the `@web5/api` package release.
+
+1. Go to the current [Version Packages PR](https://github.com/TBD54566975/tbdex-js/pulls?q=is%3Apr+author%3Aapp%2Fgithub-actions+%22Version+Packages%22+is%3Aopen)
+2. Remove the `api-release` label from the PR
+3. The release workflow should be triggered and the `@web5/api` package changes should be removed from the PR as soon as the workflow completes.
+
+#### Preview Releases
+
+With the Changesets automation, every push to main with relevant changesets, will publish the corresponding packages to the NPM registry automatically with the tag `next`.
+
+The preview releases are useful for testing and verifying the changes before publishing a stable release.
+
 #### Alpha Releases
 
 Project maintainers can release an alpha version at any time from main or feature branches. We use the