Merge pull request #15 from readwiseio/rasul/document-release-publishing

[CI] Document Release Publishing Flow

Author: rasulkireev

.github/workflows/publish-npm.yml

@@ -3,19 +3,13 @@ name: Publish npm package
 on:
   release:
     types: [published]
-  workflow_dispatch:
-    inputs:
-      tag:
-        description: "Release tag to publish, e.g. v0.5.7"
-        required: true
-        type: string
 
 permissions:
   contents: read
   id-token: write
 
 concurrency:
-  group: npm-publish-${{ github.event.release.tag_name || inputs.tag }}
+  group: npm-publish-${{ github.event.release.tag_name }}
   cancel-in-progress: false
 
 jobs:
@@ -26,15 +20,15 @@ jobs:
 
     steps:
       - name: Reject prereleases
-        if: github.event_name == 'release' && github.event.release.prerelease
+        if: github.event.release.prerelease
         run: |
           echo "::error::This workflow only publishes stable releases to npm's latest dist-tag."
           exit 1
 
-      - name: Checkout publish tag
+      - name: Checkout release tag
         uses: actions/checkout@v6
         with:
-          ref: ${{ github.event.release.tag_name || inputs.tag }}
+          ref: ${{ github.event.release.tag_name }}
           fetch-depth: 0
 
       - name: Set up Node.js
@@ -53,7 +47,7 @@ jobs:
       - name: Validate release version
         id: version
         env:
-          RELEASE_TAG: ${{ github.event.release.tag_name || inputs.tag }}
+          RELEASE_TAG: ${{ github.event.release.tag_name }}
         run: |
           set -euo pipefail
 
@@ -83,8 +77,8 @@ jobs:
             exit 1
           fi
 
-          git fetch origin master --depth=1
-          if ! git merge-base --is-ancestor HEAD FETCH_HEAD; then
+          git fetch origin +refs/heads/master:refs/remotes/origin/master
+          if ! git merge-base --is-ancestor HEAD origin/master; then
             echo "::error::Release tag ${RELEASE_TAG} must point to a commit on origin/master."
             exit 1
           fi

README.md

@@ -183,3 +183,21 @@ npm run build
 # Run without building
 npx tsx src/index.ts --help
 ```
+
+## Releasing
+
+Merging a feature PR does not publish it to users. Users receive CLI changes only after a new npm version is published by the `Publish npm package` GitHub Action.
+
+To ship a release:
+
+1. Bump `package.json` and `package-lock.json` to the next version in a release PR.
+2. Merge the release PR to `master`.
+3. Create and publish a GitHub Release whose tag exactly matches the package version with a leading `v`, for example `v0.5.8`.
+4. Wait for the `Publish npm package` action to complete. It builds the CLI, checks that the release tag matches `package.json`, verifies the lockfile versions, and publishes to npm through trusted publishing.
+5. Confirm npm shows the new version:
+
+```bash
+npm view @readwise/cli version
+```
+
+If a version is prepared but never published, skip it and bump to the next version. npm versions do not need to be contiguous.