Update README, add more comments

Author: courier-new

.github/workflows/goreleaser.yml

@@ -3,7 +3,39 @@ name: GoReleaser
 on:
   - push
 
+# There are two cases where this GitHub action will run:
+#
+# 1. We are releasing a new latest version for src-cli, as a major, minor, or patch
+#    update, for instance 4.0.2 -> 4.1.0, OR
+# 2. We are releasing a new minor/patch version for an older major/minor version of
+#    src-cli, for instance if the latest version is 4.0.2 and we're releasing 3.43.3
+#
+# In both cases, we want to run both goreleaser and npm to publish new versions in all the
+# places we care about. For goreleaser publishing to Homebrew, we need to publish to
+# different formulas depending on if we're case 1. or case 2, and neither goreleaser nor
+# Homebrew has a good way of handling this automatically. In the case of the former (a new
+# latest release), we must:
+#
+# 1. Copy the main formula in our Homebrew tap for the previous latest release to a
+#    versioned formula
+# 2. Build and publish the new release to the main formula
+# 3. Update the Homebrew symlink alias for the latest version
+#
+# In the case of the latter (a patch release for an older version), we only need to:
+#
+# 1. Build and publish the new release to a versioned Homebrew formula
+#
+# This action contains 5 jobs to accommodate both cases:
+#
+# release_type    [always]      - checks tags, determines if we're case 1. or case 2.
+# goreleaser_pre  [if case 1.]  - copies the main formula to a versioned formula
+# goreleaser      [always]      - runs tests, builds + publishes with goreleaser
+# goreleaser_post [if case 1.]  - updates symlink to latest version
+# npm             [always]      - publishes to npm
 jobs:
+  # release_type compares the most recently created tag to the highest versioned tag
+  # available on the repo to determine if this release is for a new latest version or a
+  # patch of an older version.
   release_type:
     name: Determine release type
     runs-on: ubuntu-latest
@@ -16,20 +48,19 @@ jobs:
         uses: actions/checkout@v3
         with:
           fetch-depth: 0
-      - name: Fetch most recent, latest (highest version), and second latest tags
-        # TODO: Replace most_recent echo "most_recent_tag=$(git tag --sort=taggerdate | tail -1)" >> $GITHUB_ENV
+      - name: Fetch most recent tag, latest (highest version) tag, and second latest tag
+        # TODO: to fake a patch release: echo "most_recent_tag=3.43.3" >> $GITHUB_ENV
         run: |
-          echo "most_recent_tag=3.43.3" >> $GITHUB_ENV
+          echo "most_recent_tag=$(git tag --sort=taggerdate | tail -1)" >> $GITHUB_ENV
           echo "latest_tag=$(git tag --sort=version:refname | tail -1)" >> $GITHUB_ENV
           echo "second_latest_tag=$(git tag --sort=version:refname | tail -2 | sed -n 1p)" >> $GITHUB_ENV
       - name: Install semver
         run: |
           wget -O /usr/local/bin/semver https://raw.githubusercontent.com/fsaintjacques/semver-tool/master/src/semver
           chmod +x /usr/local/bin/semver
       - name: Compare tags
-        # If the most recent tag IS the latest tag, semver compare returns 0. If it's a
-        # patch of an earlier version, semver compare will return -1. It shouldn't be
-        # possible that the most recent tag is a newer version than the latest.
+        # If the most recent tag is also the latest tag, semver compare returns 0. If it's
+        # a patch of an older version, semver compare will return -1.
         run: |
           if [[ $(semver compare ${{ env.latest_tag }} ${{ env.most_recent_tag }}) == 0 ]]
           then
@@ -40,10 +71,9 @@ jobs:
       - name: Log variables
         run: |
           echo "Most recent (current) tag: ${{ env.most_recent_tag }}"
-          echo "Latest tag: ${{ env.latest_tag }}"
+          echo "Latest version tag: ${{ env.latest_tag }}"
           echo "Building current version as new latest?: ${{ env.is_latest_version }}"
 
-
   # goreleaser_pre copies the main formula in our Homebrew tap for the previous latest
   # release (second latest tag) to a versioned formula, so that it is preserved when
   # goreleaser runs and overwrites the main formula for the latest build.
@@ -83,7 +113,7 @@ jobs:
         run: cp Formula/src-cli.rb ${{ env.versioned_formula_file }}
       # Homebrew expects the name of the class in a versioned formula file to be of the
       # format {Formula}AT{Major}{Minor}{Patch}, but the main formula classname is just
-      # {Formula}, so we manually patch the name: SrcCli -> SrcCliAT###
+      # {Formula}, so we manually update the name: SrcCli -> SrcCliAT###
       - name: Rename formula classname
         run: sed -i 's/class SrcCli/class ${{ env.versioned_classname }}/' ${{ env.versioned_formula_file }}
       - name: Commit result
@@ -95,12 +125,14 @@ jobs:
           git commit -m "Copy previous release"
           git push --dry-run
 
+  # goreleaser runs tests before building, then uses goreleaser to publish to Homebrew and
+  # Docker Hub.
   goreleaser:
     name: Run goreleaser
     runs-on: ubuntu-latest
     needs: [release_type, goreleaser_pre]
     # By default, this job will be skipped if either "needs" job is skipped. This tells
-    # GitHub actions to always run it, so long as the previous jobs didn't fail.
+    # GitHub actions to always run it, so long as the previous jobs that ran didn't fail.
     if: |
       always() &&
       (needs.release_type.result == 'success') &&
@@ -114,6 +146,9 @@ jobs:
       - name: Set variables
         run: echo "is_latest_version=${{ needs.release_type.outputs.is_latest_version }}" >> $GITHUB_ENV
       - name: Set config file
+        # These goreleaser config files are identical except for the brews.name template.
+        # Homebrew expects the main formula to be named one way, and versioned formulas to
+        # be named another, but goreleaser only allows us to specify a single template.
         run: |
           if [[ ${{ env.is_latest_version }} == 1 ]]
           then
@@ -191,6 +226,7 @@ jobs:
           git commit -m "Update latest release symlink"
           git push --dry-run
 
+  # npm publishes the new version to the npm package registry
   # npm:
   #   runs-on: ubuntu-latest
   #   needs: goreleaser

README.markdown README.mdREADME.markdown renamed to README.md

@@ -26,12 +26,18 @@ curl -L https://sourcegraph.com/.api/src-cli/src_darwin_amd64 -o /usr/local/bin/
 chmod +x /usr/local/bin/src
 ```
 
-or
+or with Homebrew:
 
 ```bash
 brew install sourcegraph/src-cli/src-cli
 ```
 
+or with npm:
+
+```bash
+npm install -g @sourcegraph/src
+```
+
 #### Version compatible with your Sourcegraph instance
 
 Replace `sourcegraph.example.com` with your Sourcegraph instance URL:
@@ -47,6 +53,12 @@ or, if you know the specific version to target, for example 3.43.2:
 brew install sourcegraph/src-cli/src-cli@3.43.2
 ```
 
+or with npm/npx:
+
+```bash
+npx @sourcegraph/src@3.43.2 version
+```
+
 > Note: Versioned formulas are available on Homebrew for Sourcegraph versions 3.43.2 and later.
 
 ### Installation: Linux
@@ -58,6 +70,12 @@ curl -L https://sourcegraph.com/.api/src-cli/src_linux_amd64 -o /usr/local/bin/s
 chmod +x /usr/local/bin/src
 ```
 
+or with npm:
+
+```bash
+npm install -g @sourcegraph/src
+```
+
 #### Version compatible with your Sourcegraph instance
 
 Replace `sourcegraph.example.com` with your Sourcegraph instance URL:
@@ -67,6 +85,12 @@ curl -L https://sourcegraph.example.com/.api/src-cli/src_linux_amd64 -o /usr/loc
 chmod +x /usr/local/bin/src
 ```
 
+or, with npm/npx, if you know the specific version to target, for example 3.43.2:
+
+```bash
+npx @sourcegraph/src@3.43.2 version
+```
+
 ### Installation: Windows
 
 See [Sourcegraph CLI for Windows](WINDOWS.md).