vercel__chat/RELEASE.md

Release Process

This project uses Changesets for version management and automated npm publishing.

How Changesets Work

Changesets is a tool that manages versioning and changelogs for monorepos. The workflow is:

1. Contributors add changesets when making changes that should trigger a release
2. CI creates a "Version Packages" PR that accumulates all changesets
3. Merging the Version PR triggers npm publishing

For Contributors

Adding a Changeset

When you make a change that should be released (bug fix, new feature, breaking change), run:

pnpm changeset

This interactive CLI will ask:

1. Which packages changed? - Select affected packages (space to select, enter to confirm)
2. Bump type? - major (breaking), minor (feature), or patch (fix)
3. Summary - A brief description for the changelog

This creates a markdown file in .changeset/ describing your change. Commit this file with your PR.

Example

$ pnpm changeset

🦋  Which packages would you like to include?
   ◯ @chat-adapter/gchat
   ◉ @chat-adapter/slack
   ◯ @chat-adapter/teams
   ...

🦋  Which packages should have a major bump?
   (Press <space> to select, <enter> to proceed)

🦋  Which packages should have a minor bump?
   ◉ @chat-adapter/slack

🦋  Please enter a summary for this change:
   Added support for file uploads in Slack

🦋  Summary: Added support for file uploads in Slack

🦋  === Summary of changesets ===
🦋  minor: @chat-adapter/slack

🦋  Is this your desired changeset? (Y/n) Y
🦋  Changeset added!

When to Add a Changeset

• Do add for: bug fixes, new features, breaking changes, dependency updates affecting behavior
• Don't add for: documentation changes, internal refactors, test changes, CI updates

Changeset Types

Type	When to Use	Version Bump
patch	Bug fixes, minor improvements	4.0.0 → 4.0.1
minor	New features (backward compatible)	4.0.0 → 4.1.0
major	Breaking changes	4.0.0 → 5.0.0

Automated Release Process

How It Works

1. When PRs with changesets are merged to main, CI runs
2. The changesets/action detects pending changesets
3. It creates/updates a "Version Packages" PR with:
   • Version bumps in package.json files
   • Updated CHANGELOG.md files
   • Consumed changeset files (deleted)
4. When you merge the "Version Packages" PR:
   • CI runs again
   • Packages are published to npm
   • Git tags are created

Linked Packages

All packages in this monorepo are linked (configured in .changeset/config.json):

"linked": [["chat", "@chat-adapter/*"]]

This means when any package gets a minor or major bump, all linked packages are bumped together to keep versions in sync.

Required Secrets

The GitHub Actions workflow requires these secrets:

NPM_TOKEN (Required)

An npm access token with publish permissions for the @chat-adapter scope and chat package.

To create:

1. Go to npmjs.com → Account Settings → Access Tokens
2. Click "Generate New Token" → "Classic Token"
3. Select Automation type (for CI/CD)
4. Copy the token

To add to GitHub:

1. Go to your repo → Settings → Secrets and variables → Actions
2. Click "New repository secret"
3. Name: NPM_TOKEN
4. Value: paste your npm token
5. Click "Add secret"

GITHUB_TOKEN (Automatic)

This is automatically provided by GitHub Actions. No setup needed.

It's used to:

• Create the "Version Packages" PR
• Push version commits
• Create git tags

Manual Publishing (Emergency)

If you need to publish manually (not recommended):

# Ensure you're logged in to npm
npm login

# Build all packages
pnpm build

# Run changeset version to update versions
pnpm changeset version

# Publish to npm
pnpm changeset publish

Configuration

The changeset config is in .changeset/config.json:

{
  "changelog": "@changesets/cli/changelog",
  "commit": false,
  "fixed": [],
  "linked": [["chat", "@chat-adapter/*"]],
  "access": "public",
  "baseBranch": "main",
  "updateInternalDependencies": "patch",
  "ignore": ["example-nextjs-chat", "@chat-adapter/integration-tests"]
}

Option	Value	Description
access	"public"	Publish scoped packages publicly
baseBranch	"main"	Branch to compare against
linked	[["chat", "@chat-adapter/*"]]	Keep versions in sync
ignore	["example-nextjs-chat", ...]	Don't publish these packages
updateInternalDependencies	"patch"	Auto-bump dependents on patch releases

Troubleshooting

"npm ERR! 403 Forbidden"

• Check that NPM_TOKEN secret is set correctly
• Verify the token has publish permissions
• Ensure you're a member of the @chat-adapter npm organization

"Version Packages" PR not created

• Ensure there are changeset files in .changeset/
• Check that the workflow ran successfully
• Verify GITHUB_TOKEN has write permissions

Packages not publishing

• Check the "Version Packages" PR was merged (not just changesets)
• Verify all tests pass in CI
• Check npm for rate limiting issues

First Release Checklist

Before the first publish:

1. Create the @chat-adapter organization on npm
2. Add team members to the npm org
3. Generate an npm automation token
4. Add NPM_TOKEN secret to GitHub
5. Verify all package.json files have "publishConfig": { "access": "public" }
6. Run pnpm changeset to create initial changeset
7. Merge to main and watch the magic happen