Skip to content

docs(repo): update release docs #1835

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
mandarini merged 1 commit into from
Nov 5, 2025
+66 −64
Merged

docs(repo): update release docs #1835

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
18 changes: 8 additions & 10 deletions docs/MIGRATION.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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?

Expand Down Expand Up @@ -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

Expand All @@ -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/[email protected]
npm install @supabase/[email protected]
```

⚠️ **Warning:** Using Node.js 18 is not recommended as it no longer receives security updates.
Expand Down
112 changes: 58 additions & 54 deletions docs/RELEASE.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -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
Expand All @@ -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:

Expand All @@ -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
Expand All @@ -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`
Expand All @@ -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)

Expand All @@ -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

Expand All @@ -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