Add GHA workflow to publish releases; stale file cleanup

.github/workflows/release.yml

@@ -0,0 +1,66 @@
+name: Release
+
+on:
+  push:
+    tags:
+      - 'v[0-9]+.[0-9]+.[0-9]+'
+  workflow_dispatch:
+    inputs:
+      version:
+        description: 'Version tag to release, e.g. v4.3.1'
+        required: true
+        type: string
+
+permissions:
+  contents: write
+
+jobs:
+  Release:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v7
+        with:
+          persist-credentials: false
+
+      - name: Resolve tag
+        id: tag
+        env:
+          EVENT_NAME: ${{ github.event_name }}
+          REF_NAME: ${{ github.ref_name }}
+          INPUT_VERSION: ${{ inputs.version }}
+        run: |
+          if [ "$EVENT_NAME" = "workflow_dispatch" ]; then
+            tag="$INPUT_VERSION"
+          else
+            tag="$REF_NAME"
+          fi
+          echo "tag=$tag" >> "$GITHUB_OUTPUT"
+
+      - name: Create and push tag
+        if: github.event_name == 'workflow_dispatch'
+        env:
+          GH_TOKEN: ${{ github.token }}
+          TAG: ${{ steps.tag.outputs.tag }}
+          HEAD_REF: ${{ github.ref }}
+        run: |
+          if [ "$HEAD_REF" != "refs/heads/main" ]; then
+            echo "Dispatch releases must run from main; got $HEAD_REF" >&2
+            exit 1
+          fi
+          if ! printf '%s' "$TAG" | grep -Eq '^v[0-9]+\.[0-9]+\.[0-9]+$'; then
+            echo "Version must look like v1.2.3; got '$TAG'" >&2
+            exit 1
+          fi
+          if gh api "repos/$GITHUB_REPOSITORY/git/ref/tags/$TAG" >/dev/null 2>&1; then
+            echo "Tag $TAG already exists" >&2
+            exit 1
+          fi
+          git tag "$TAG"
+          git push "https://x-access-token:${GH_TOKEN}@github.com/${GITHUB_REPOSITORY}.git" "refs/tags/$TAG"
+
+      - name: Publish GitHub Release
+        env:
+          GH_TOKEN: ${{ github.token }}
+          TAG: ${{ steps.tag.outputs.tag }}
+        run: gh release create "$TAG" --generate-notes --verify-tag

.gitignore

@@ -34,6 +34,3 @@ tempvendor
 
 # Database
 data
-
-# Charts temp dir
-.chart

README.md

@@ -58,32 +58,27 @@ run the integration and end-to-end tests.
 
 ## Testing
 
-We test multiple modules by default. Therefore, if you wish to test a specific
-package, you must specify the `MODULE` env variable. See the examples below. 
+`just test` runs the Go unit tests for the whole module. Any arguments are
+passed through to `go test`, so a package pattern scopes the run to specific
+packages.
 
 Examples:
 
 ```bash
 # Run all Go tests
 just test
 
-# Run all Go tests twice
-just test -count 2 ./...
-
 # Run all tests once (no cached results)
 just test -count 1 ./...
 
 # Run with verbose output
 just test -v ./...
 
-# Run the "TestNewDebugLog" test twice with verbose output
-MODULE=pkg/rslog just test -v -count 2 github.com/rstudio/platform-lib/pkg/rslog/debug -testify.m=TestNewDebugLog
-
-# Run the LocalNotifySuite suite tests with verbose output
-MODULE=pkg/rsnotify just test -v github.com/rstudio/platform-lib/pkg/rsnotify/locallistener -check.f=LocalNotifySuite
+# Test a single package subtree
+just test ./pkg/rslog/...
 
-# Run the PgxNotifySuite suite tests with docker-compose
-MODULE=pkg/rsnotify just test-integration -v github.com/rstudio/platform-lib/pkg/rsnotify/pgxlistener -check.f=PgxNotifySuite
+# Run one gocheck suite in a package, verbose
+just test -v ./pkg/rsnotify/listeners/local/... -check.f=LocalNotifySuite
 ```
 
 ### Testing with Docker
@@ -102,23 +97,30 @@ just test-integration
 To update `NOTICE.md` with a list of licenses from third-party Go modules,
 use the `just licenses` target. This requires Python 3.
 
-## Versioning
+## Release
 
-Follow semantic versioning guidelines. To release a new version, we simply
-create and push a tag.
+The repo is a single Go module (`github.com/rstudio/platform-lib/v4`), so a
+single tag versions the whole library. Follow semantic versioning.
+
+To release, tag the merge commit on `main` and push it. The `Release` workflow
+(`.github/workflows/release.yml`) then publishes a GitHub Release with an
+auto-generated changelog.
 
 ```shell
-git tag v0.1.2
-git push origin v0.1.2
+git tag v4.3.0
+git push origin v4.3.0
 ```
 
-The `rslog` package is versioned separately. To release a new `rslog` version:
+Or run the workflow manually to create the tag and release in one step,
+without touching local git:
 
 ```shell
-git tag pkg/rslog/v1.6.1
-git push origin pkg/rslog/v1.6.1
+gh workflow run release.yml -f version=v4.3.1
 ```
 
+A major bump (e.g. v3 to v4) also requires updating the `/vN` suffix in the
+module path and all import paths, not just the tag.
+
 ## Badges
 
 * [Go Report Card](https://goreportcard.com/) - It will scan your code with

justfile

@@ -72,13 +72,7 @@ bash:
 clean:
     rm -rf out/
     rm -rf data/
-    rm -rf .chart/
 
 # generate Go dependencies' licenses file
 licenses:
     ./scripts/go-licenses.sh
-
-# enumerate latest tags for each module
-tags: versions
-versions:
-    ./scripts/latest-tags.sh

pkg/README.md

@@ -16,20 +16,9 @@ It's also a way to group Go code in one place when your root directory contains
 lots of non-Go components and directories making it easier to run various Go
 tools.
 
-## Go Modules
+## Go Module
 
-Each subdirectory of `/pkg` is a separate Go module and should contain its own
-`go.mod`. You can release an individual module easily by creating a tag that 
-contains the subdirectory. For example, to release `rslog` `1.0.1`, you would
-create a tag like this:
-
-```bash
-git tag pkg/rslog/v1.0.1
-git push origin --tags
-```
-
-Before creating a tag, ensure that the `go.mod` has been updated with the
-correct dependency versions for other `platform-lib` packages. For example,
-the local listener module at `/pkg/rsnotify/listeners/local` depends upon the
-`/pkg/rsnotify` module, so we must ensure that the local listener's `go.mod`
-references the correct `rsnotify` version.
+Everything under `/pkg` is part of the single root module
+(`github.com/rstudio/platform-lib/v4`) and is versioned by the repo's top-level
+tags. See the "Release" section of the top-level [README](../README.md) for how
+releases are cut.

pkg/rscache/internal/integration_test/README.md

@@ -3,17 +3,16 @@
 ## Description
 
 Includes unit tests that exercise the cache against a file storage server
-implemented in `pkg/rsstorage/servers/file`. Since these tests must import
-the file server module, we package them separately so other 
-applications don't need to import all the implementations and their
-dependencies.
+implemented in `pkg/rsstorage/servers/file`. Since these tests import the
+file server implementation, they live in this `internal` package so other
+applications don't pull in the implementations and their dependencies.
 
 These tests can be run with:
 
 ```bash
 # All tests
 just test
 
-# All tests in this module
-MODULE=pkg/rscache/internal/integration_test just test
+# Just these tests
+just test ./pkg/rscache/internal/integration_test/...
 ```

pkg/rsnotify/README.md

@@ -18,7 +18,7 @@ specific notification that matches a filter.
 
 ## Implementations
 
-Each listener implementation is a separate Go module.
+Each listener implementation is a separate package.
 
 ### listeners/local
 

pkg/rsstorage/internal/integration_test/README.md

@@ -3,17 +3,16 @@
 ## Description
 
 Includes unit tests that exercise all the storage servers
-implemented in `pkg/rsstorage/servers/*`. Since these tests must import
-all the implementation modules, we package them separately so other 
-applications don't need to import all the implementations and their
-dependencies.
+implemented in `pkg/rsstorage/servers/*`. Since these tests import all the
+storage server implementations, they live in this `internal` package so other
+applications don't pull in those implementations and their dependencies.
 
 These tests can be run with:
 
 ```bash
 # All tests
 just test-integration
 
-# All tests in this module
-MODULE=pkg/rsstorage/internal/integration_test just test-integration
+# Just these tests
+just test-integration ./pkg/rsstorage/internal/integration_test/...
 ```