Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
132 lines (95 loc) · 3.58 KB

CONTRIBUTING.md

File metadata and controls

132 lines (95 loc) · 3.58 KB

Contributing to ChatCops

Development Setup

# Fork the repo on GitHub, then clone your fork
git clone https://github.com/<your-username>/chatcops.git
cd chatcops

# Add upstream remote
git remote add upstream https://github.com/codercops/chatcops.git

# Install dependencies
pnpm install

# Build all packages
pnpm -r build

# Run tests
pnpm test

# Typecheck
pnpm -r typecheck

Project Structure

packages/
  core/     - @chatcops/core (AI providers, tools, knowledge base)
  widget/   - @chatcops/widget (embeddable chat UI)
  server/   - @chatcops/server (server handler + adapters)
website/    - Marketing site + Starlight docs (Astro)

Development Workflow

  1. Sync your fork's dev branch with upstream: 
    git fetch upstream
git checkout dev
git merge upstream/dev
  2. Work directly on your fork's dev branch — commit and push as you go
  3. Run tests: pnpm test
  4. Run typecheck: pnpm -r typecheck
  5. Add a changeset if your changes affect published packages: pnpm changeset
  6. When ready, open a PR from your fork's dev → upstream dev

Branch Strategy

  • dev — default branch, all development happens here
  • production — release branch, merged from dev when cutting a release
  • PRs should target dev unless you're doing a production release

Releasing to Production

When dev is ready to ship:

  1. Ensure all changes that affect published packages have changesets:

    pnpm changeset

    This creates a changeset file describing the version bump (patch/minor/major) and a summary. Commit it to dev.

  2. Create a PR from dev → production and merge it.

  3. The Release workflow runs automatically on production push:

    • Builds, typechecks, and tests everything
    • If unreleased changesets exist, Changesets action opens a "Version Packages" PR on production that bumps versions and updates changelogs
    • Merging that PR triggers the workflow again, which publishes to npm (via OIDC trusted publishing)

  4. The website is auto-deployed by the Vercel GitHub integration — no manual step needed.

Note: Only maintainers can merge into production. If you're a contributor, just make sure your PR to dev includes a changeset when needed.

Widget Development

# Build widget in watch mode
cd packages/widget
pnpm dev

# Open dev.html in a browser for live testing

To test with a real backend, run the Express example:

cd packages/server
ANTHROPIC_API_KEY=sk-... npx tsx src/examples/express-server.ts

Adding a New AI Provider

  1. Create packages/core/src/providers/{name}.ts
  2. Implement the AIProvider interface
  3. Add a format converter in base.ts
  4. Register in the createProvider factory
  5. Export from index.ts
  6. Add tests

Adding a New Locale

  1. Create packages/core/src/i18n/{code}.ts
  2. Export all LocaleStrings fields
  3. Register in packages/core/src/i18n/index.ts
  4. Add to the test in tests/i18n/locales.test.ts

Website Development

cd website
pnpm dev

The website requires a .env.local file with:

# Required — powers the live chat demo on the landing page
OPENAI_API_KEY=sk-...

# Optional — visitor counter (Upstash Redis)
UPSTASH_REDIS_REST_URL=https://your-endpoint.upstash.io
UPSTASH_REDIS_REST_TOKEN=your-token-here

The visitor counter gracefully degrades without Upstash credentials (displays -). Google Analytics (G-GLYL9J6QYX) is hardcoded in the layout and Starlight config.

Commit Convention

Use conventional commits: feat:, fix:, chore:, docs:, test:, refactor: