vercel__chat/.github/CONTRIBUTING.md

Contributing

Development

Testing

Run all unit tests across every package in a single Vitest Workspace run:

pnpm test:workspace

This produces one combined report covering all 11 unit-test packages. Integration tests (@chat-adapter/integration-tests) are excluded since they require platform credentials.

You can also run tests per-package via Turborepo:

# All packages (including integration tests)
pnpm test

# Single package
pnpm --filter chat test
pnpm --filter @chat-adapter/slack test

Other commands

pnpm check       # Check all packages (linting and formatting)
pnpm typecheck   # Type-check all packages
pnpm knip        # Check for unused exports/dependencies
pnpm validate    # Run everything (knip, lint, typecheck, test, build)

Preview Branch Testing

The example app includes a middleware that can proxy webhook requests to a preview branch deployment. This allows testing preview branches with real webhook traffic from Slack/Teams/GChat.

Setup

1. Deploy a preview branch to Vercel (e.g., https://chat-sdk-git-feature-branch.vercel.app)
2. Go to /settings on the production deployment
3. Enter the preview branch URL and save

To disable

Clear the URL on the settings page.

Files

• examples/nextjs-chat/src/middleware.ts - The proxy middleware
• examples/nextjs-chat/src/app/settings/page.tsx - Settings UI
• examples/nextjs-chat/src/app/api/settings/preview-branch/route.ts - API to get/set the URL

---

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

Fixed Versioning

All packages in this monorepo use fixed versioning (configured in .changeset/config.json):

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

This means all packages always have the same version number. When any package is released, all packages are released together with the same version bump.

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": [["chat", "@chat-adapter/*"]],
  "linked": [],
  "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
fixed	[["chat", "@chat-adapter/*"]]	All packages always have same version
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