docs(repo): update release docs (#1835)

Author: mandarini

docs/MIGRATION.md

@@ -12,7 +12,7 @@
 
 ### What Changed
 
-Starting with version `2.XX.0` (where XX is the version where this change is released), all Supabase JavaScript libraries require **Node.js 20 or later**. The `@supabase/node-fetch` polyfill has been removed, and native fetch support is now required.
+Starting with version `2.79.0`, all Supabase JavaScript libraries require **Node.js 20 or later**. The `@supabase/node-fetch` polyfill has been removed, and native fetch support is now required.
 
 ### Why?
 
@@ -55,12 +55,12 @@ npm install @supabase/auth-js@latest
 
 ### Supported Environments
 
-✅ **Node.js 20+** - Native fetch support
-✅ **Modern browsers** - Chrome 42+, Firefox 39+, Safari 10.1+, Edge 14+
-✅ **Deno 1.0+** - Native fetch built-in
-✅ **Bun 0.1+** - Native fetch built-in
-✅ **React Native** - With fetch polyfill provided by the framework
-✅ **Expo** - With fetch polyfill provided by the framework
+- **Node.js 20+** - Native fetch support
+- **Modern browsers** - All modern browsers
+- **Deno 1.0+** - Native fetch built-in
+- **Bun 0.1+** - Native fetch built-in
+- **React Native** - With fetch polyfill provided by the framework
+- **Expo** - With fetch polyfill provided by the framework
 
 ### Troubleshooting
 
@@ -76,9 +76,7 @@ This means you're running Node.js < 20. Solutions:
 If you must use Node.js 18, install the last version that supported it:
 
 ```bash
-# Find the last version that supported Node.js 18
-# (This will be version 2.XX.X where XX is one less than the version with this change)
-npm install @supabase/supabase-js@2.XX.X
+npm install @supabase/supabase-js@2.78.0
 ```
 
 ⚠️ **Warning:** Using Node.js 18 is not recommended as it no longer receives security updates.

docs/RELEASE.md

@@ -1,51 +1,46 @@
 # Release Workflows
 
-- [.github/workflows/main-ci-release.yml](.github/workflows/main-ci-release.yml) - Main CI & automated canary releases
-- [.github/workflows/release-stable.yml](.github/workflows/release-stable.yml) - Manual stable releases
+- [.github/workflows/publish.yml](.github/workflows/publish.yml) - Canary and stable releases
 - [.github/workflows/preview-release.yml](.github/workflows/preview-release.yml) - PR preview releases
 
 ## Overview
 
 This monorepo uses a fixed release model where all packages share a single version number and are released together. There are three types of releases:
 
-1. **Canary Releases** - Automated pre-releases on every commit to master
-2. **Stable Releases** - Manual releases for production use
+1. **Canary Releases** - Automated pre-releases on every conventional commit to `master`
+2. **Stable Releases** - Manual releases for production use (requires maintainer permission)
 3. **Preview Releases** - PR-specific releases for testing changes
 
 ## Workflows
 
 ### 🤖 Canary Releases (Automated)
 
-**File:** `main-ci-release.yml`  
-**Trigger:** Every push to `master` branch  
+**Workflow:** `publish.yml`  
+**Trigger:** Every push to `master` branch (after CI passes)  
+**Script:** `scripts/release-canary.ts`  
 **Purpose:** Immediate feedback with pre-release versions
 
 #### What it does
 
-1. **CI Pipeline**: Runs all CI checks
-2. **Version Bump**: Creates a new pre-release version using conventional commits
-
-3. **NPM Publish**: Publishes all packages to npm with `canary` dist-tag
-4. **GitHub Release**: Creates a pre-release tag on GitHub with changelog
+1. **Checks for conventional commits** - Only releases if commits warrant a version bump
+2. **Version Bump** - Creates a new pre-release version using `prerelease` specifier with `canary` preid
+3. **Build** - Rebuilds all packages with updated versions
+4. **Changelog** - Generates changelogs from conventional commits
+5. **NPM Publish** - Publishes all packages to npm with `canary` dist-tag (marked as prerelease)
+6. **Legacy Package** - Publishes `@supabase/gotrue-js` as legacy mirror of `auth-js`
 
 #### Example flow
 
-- Make a change
-
 ```bash
 # Commit with conventional format
 git commit -m "fix(auth): resolve token refresh issue"
+# Merge PR to master
+# → CI runs and passes
+# → Version bumped to e.g., 2.80.1-canary.0
+# → Published to npm with 'canary' dist-tag
+# → All packages versioned identically
 ```
 
-- Open PR and get it merged to `master`
-
-- Then:
-  → CI runs and passes
-  → Version bumped to e.g., 2.80.1-canary.0
-  → Published to npm with 'canary' dist-tag
-  → GitHub pre-release tag created
-  → All packages versioned identically
-
 #### Install canary versions
 
 ```bash
@@ -55,21 +50,29 @@ npm install @supabase/auth-js@canary
 npm install @supabase/storage-js@canary
 ```
 
+**Note:** Canary releases are skipped if no conventional commits are detected that warrant a release.
+
 ### 👨‍💻 Stable Releases (Manual)
 
-**File:** `release-stable.yml`  
-**Trigger:** Manual workflow dispatch (repository owners only)  
+**Workflow:** `publish.yml` (manual trigger)  
+**Script:** `scripts/release-stable.ts`  
+**Trigger:** Manual workflow dispatch by maintainers  
+**Permission:** Members of `@supabase/admin` or `@supabase/sdk` teams only  
 **Purpose:** Production-ready releases for end users
 
 #### How it works
 
-1. **Version Specification**: Repository owner provides a version specifier
+1. **Version Specification**: Maintainer provides a version specifier via workflow input
 2. **Version Bump**: Nx applies the version change to all packages
-3. **Changelog Update**: Generates changelogs from conventional commits
-4. **NPM Publish**: Publishes all packages with `latest` dist-tag
-5. **PR Creation**: Automatically creates a PR with changelog updates
+3. **Build**: Rebuilds all packages with updated versions
+4. **Changelog Update**: Generates changelogs from conventional commits (since last stable tag)
+5. **NPM Publish**: Publishes all packages with `latest` dist-tag
+6. **Legacy Package**: Publishes `@supabase/gotrue-js` as legacy mirror
+7. **Release Branch**: Creates a release branch with changelog updates
+8. **PR Creation**: Automatically creates and auto-merges a PR with changelog updates
+9. **Documentation**: Triggers documentation update workflow
 
-#### Version Specifiers (for repo owners)
+#### Version Specifiers
 
 You can specify the version in two ways:
 
@@ -89,13 +92,13 @@ You can specify the version in two ways:
 
 ### 🔄 Preview Releases (PR-based)
 
-**File:** `preview-release.yml`  
+**Workflow:** `preview-release.yml`  
 **Trigger:** PR with `trigger: preview` label  
 **Purpose:** Test PR changes before merging
 
 #### How it works
 
-1. **Label Trigger**: Contributors request preview by asking maintainers to add label
+1. **Label Trigger**: Contributors request preview by asking maintainers to add `trigger: preview` label
 2. **Build**: Builds all affected packages
 3. **Publish**: Uses [pkg.pr.new](https://pkg.pr.new) to create preview packages
 4. **Comment**: Adds installation instructions to PR
@@ -121,15 +124,16 @@ Canary releases are **fully automated**. Simply:
 2. Use conventional commits with type and scope (e.g., `fix(auth):`, `feat(realtime):`, `chore(repo):`)
 3. Create and merge PR to `master` branch
 4. Workflow automatically:
-   - Runs CI checks
-   - Creates pre-release version
+   - Runs CI checks (`ci-core` and `ci-supabase-js`)
+   - Checks for conventional commits that warrant a release
+   - Creates pre-release version (skips if no commits warrant release)
    - Publishes to npm with `canary` tag
-   - Creates GitHub pre-release
+   - Creates GitHub changelog entries
 
-### Running Stable Release (repository owners only)
+### Running Stable Release (maintainers only)
 
 1. **Navigate to Actions tab** in GitHub repository
-2. **Select "Release Stable"** workflow
+2. **Select "Publish releases"** workflow
 3. **Click "Run workflow"**
 4. **Enter version specifier:**
    - For patch release: `patch`
@@ -138,11 +142,14 @@ Canary releases are **fully automated**. Simply:
    - For specific version: `v2.81.0` or `2.81.0`
 5. **Click "Run workflow"**
 6. **Workflow automatically:**
+   - Validates you're a member of `@supabase/admin` or `@supabase/sdk`
    - Bumps version for all packages
-   - Generates changelogs
+   - Generates changelogs since last stable tag
    - Publishes to npm with `latest` tag
-   - Creates release branch and PR
+   - Creates release branch and PR with changelog updates
    - Enables auto-merge on PR
+   - Triggers documentation update workflow
+   - Sends Slack notifications
 
 ### Requesting Preview Release (contributors)
 
@@ -165,23 +172,19 @@ Canary releases are **fully automated**. Simply:
 - Generated from conventional commits
 - Per-package CHANGELOG.md files
 - Unchanged packages show "No user-facing changes in this release"
-- GitHub releases created automatically
+- Stable releases generate changelogs from last stable tag
 
 ### 🔐 Security & Permissions
 
 - Canary releases use GitHub App token for automation
-- Stable releases restricted to repository owners
-- NPM publishing uses secure tokens
+- Stable releases restricted to `@supabase/admin` or `@supabase/sdk` team members
+- NPM publishing uses OIDC trusted publishing
 - All releases signed and traceable
 
-### Nx Release Configuration
-
-The workflows rely on `nx.json` release configuration:
-
 ### Release Scripts
 
-- **`scripts/release-canary.ts`** - Handles canary releases with `canary` preid
-- **`scripts/release-stable.ts`** - Handles stable releases with version specifier input
+- **`scripts/release-canary.ts`** - Handles canary releases with `canary` preid, skips if no conventional commits
+- **`scripts/release-stable.ts`** - Handles stable releases with version specifier input, creates release branch and PR
 
 ## Best Practices
 
@@ -192,24 +195,25 @@ The workflows rely on `nx.json` release configuration:
    - `feat(realtime):` for new features (minor release)
    - `feat(repo)!:` or `BREAKING CHANGE:` for breaking changes (major release)
 2. **Request preview releases** for complex PRs
-3. **Monitor canary releases** to verify your changes
+3. **Monitor canary releases** to verify your changes work as expected
 
-### For Repository Owners
+### For Maintainers
 
 1. **Release cadence**:
-   - Canary: Automatic on every `master` commit
-   - Stable: Weekly or as needed
+   - Canary: Automatic on every `master` commit (if conventional commits present)
+   - Stable: Weekly or as needed based on canary feedback
    - Major: Coordinate with team and users
 2. **Version strategy**:
    - Use `patch` for bug fixes
    - Use `minor` for new features
    - Use `major` for breaking changes
 3. **Monitor package health** after releases
-4. **Review PR auto-merge** from release workflow
+4. **Review PR auto-merge** from release workflow (changelog updates)
+5. **Verify documentation** updates after stable releases
 
 ### For Emergency Releases
 
 1. **Fix in `master` first** - Apply fix and let canary release
 2. **Test canary** - Verify fix works in canary version
-3. **Release stable** - Use stable workflow with `patch`
-4. **Document incident** - Update changelog with details
+3. **Release stable** - Use stable workflow with `patch` specifier
+4. **Document incident** - Update changelog with details if needed