docs: add prerelease setup guide

Author: abueide

.husky/commit-msg

@@ -1,4 +1,4 @@
 #!/usr/bin/env sh
 . "$(dirname -- "$0")/_/husky.sh"
 
-yarn commitlint --edit $1
+devbox run -- yarn commitlint --edit $1

PRERELEASE_SETUP.md

@@ -24,16 +24,19 @@ Note: `chore/*` branches do not publish - they're for internal changes not meant
 Since semantic-release now controls which branches can publish based on `release.config.js`, you can either:
 
 **Option A: Allow any branch** (Recommended)
+
 - Leave "Deployment branches and tags" set to "All branches"
 - semantic-release will handle branch filtering
 
 **Option B: Restrict to specific patterns**
+
 - Select "Protected branches and tags only"
 - Add patterns: `fix/*`, `feat/*`, `beta`
 
 ### 3. Add Required Reviewers (Optional)
 
 If you want manual approval before publishing:
+
 - Enable "Required reviewers"
 - Add reviewers from your team
 - Set wait timer if desired
@@ -45,12 +48,14 @@ The environment needs access to npm for publishing. You have two options:
 #### Option A: npm Token (Traditional)
 
 1. Generate an npm automation token:
+
    ```bash
    npm login
    npm token create --type=automation
    ```
 
 2. Add the token as a secret:
+
    - Click "Add secret"
    - Name: `NPM_TOKEN`
    - Value: `npm_xxx...` (your automation token)
@@ -69,21 +74,25 @@ The environment needs access to npm for publishing. You have two options:
 #### Option B: npm Provenance with OIDC (Recommended)
 
 The current setup uses npm provenance with OIDC, which doesn't require storing an NPM_TOKEN. This is more secure because:
+
 - No long-lived tokens to manage
 - Automatic provenance attestation
 - Built-in supply chain security
 
 **No additional npm setup needed!** The workflow already has:
+
 - `id-token: write` permission
 - `@semantic-release/npm` with `provenance: true`
 
 npm will automatically authenticate using GitHub's OIDC provider.
 
 **Requirements:**
+
 - The `@segment` npm organization must have publishing from GitHub Actions enabled
 - The package must be public or the org must be on a paid npm plan
 
 To verify OIDC is configured:
+
 1. Go to: https://www.npmjs.com/settings/segment/packages
 2. Check that "Publish" permissions include GitHub Actions
 3. If not, contact npm org admin to enable it
@@ -98,6 +107,7 @@ gh workflow run release.yml -f type=dry-run --ref fix/your-branch
 ```
 
 This will:
+
 - Run CI checks
 - Simulate the release process
 - Show what would be published (without actually publishing)
@@ -110,6 +120,7 @@ gh workflow run release.yml -f type=prerelease --ref fix/your-branch
 ```
 
 This will:
+
 - Run CI checks
 - Run E2E tests
 - Publish to npm with the appropriate dist-tag
@@ -144,8 +155,9 @@ npm install @segment/analytics-react-native@2.22.1-fix.1
 ### "semantic-release says no version will be published"
 
 Check that your branch name matches one of the configured patterns in `release.config.js`:
+
 - `fix/*` - bug fixes for client distribution
-- `feat/*` - new features for client distribution  
+- `feat/*` - new features for client distribution
 - `beta` - explicit beta channel
 - `master` - production releases
 - Version branches like `1.x` or `1.2.x` - maintenance releases
@@ -155,18 +167,21 @@ Note: `chore/*` branches intentionally don't publish as they're for internal cha
 ### "npm publish failed with 403"
 
 If using Option A (npm token):
+
 - Verify `NPM_TOKEN` is set in the environment secrets
 - Check the token has publish permissions: `npm token list`
 - Ensure the token hasn't expired
 
 If using Option B (OIDC):
+
 - Verify the GitHub Actions OIDC provider is configured in npm org settings
 - Check that `id-token: write` permission is set in the workflow
 - Ensure `provenance: true` is set in semantic-release npm plugin config
 
 ### "Environment branch policy blocking publish"
 
 If you set "Protected branches only" in the environment:
+
 - Make sure your branch pattern is added to the protection rules
 - Or switch to "All branches" and rely on semantic-release filtering
 
@@ -181,11 +196,13 @@ If you set "Protected branches only" in the environment:
 ## Migrating from Old "Beta" Setup
 
 The old setup used `{ name: '*', prerelease: 'beta' }` which made ALL non-master branches publish as "beta". This was confusing because:
+
 - Fix branches weren't actually beta releases
 - You couldn't have multiple prerelease channels
 - The GitHub environment was called "Publish-Beta" but handled all prereleases
 
 The new setup is more explicit and semantically correct:
+
 - Each branch category gets its own channel
 - The environment is now "Publish-Prerelease" to reflect its broader scope
 - "beta" is now an explicit channel for the `beta` branch only

devbox.json

@@ -24,11 +24,11 @@
       "ci:install": ["yarn install --immutable"],
       "ci:commitlint": ["bash -c 'echo \"$PR_TITLE\" | yarn commitlint'"],
       "check": [
-        "devbox run lint",
-        "devbox run format-check",
-        "devbox run build",
-        "devbox run typecheck",
-        "devbox run test"
+        "yarn lint",
+        "yarn format:check",
+        "yarn build",
+        "yarn typecheck",
+        "yarn test"
       ],
       "build": ["yarn build"],
       "test": ["yarn test"],