| name | contributing |
| description | Branch naming, changeset authoring, and PR conventions for this monorepo. Use when creating branches, committing, writing changesets, opening PRs, or running pre-merge checks. |
Contributing
Branch Naming
main (protected, always releasable)
├── feat/add-streaming-cache
├── fix/anthropic-tool-parsing
└── chore/update-deps
| Prefix | Use |
|---|
feat/ | New feature or capability |
fix/ | Bug fix |
chore/ | Tooling, deps, CI, docs |
refactor/ | Code restructuring without behavior change |
No long-lived develop or release/* branches. Feature/fix branches are short-lived, branched from main, merged via PR.
Changesets
Every PR must include a changeset. Changesets drive version bumps and changelog generation.
Creating a changeset
Prefer the interactive CLI:
npm run changeset
This prompts for affected packages, bump type, and a summary, then writes a .changeset/<random-name>.md file.
Changeset file format
If writing a changeset by hand, use this exact format:
---
'@core-ai/core-ai': minor
---
Short description of the change for the changelog.
Rules:
- YAML frontmatter between
--- delimiters (required)
- Package names are quoted with single quotes and include the scope
- Bump type is one of:
patch, minor, major
- Body below the frontmatter is the changelog entry
- Default to one package per file. Listing multiple packages in one file's frontmatter copies the same body text to every listed package's changelog — it does not produce package-specific entries.
Pre-1.0 versioning
While packages are below 1.0.0, use minor for breaking changes instead of major. Changesets does not auto-downgrade major bumps for pre-1.0 packages -- a major on 0.x.y will jump straight to 1.0.0. Use major only when intentionally releasing 1.0.0.
Fixed version group
All publishable packages share a single version number (the fixed group in .changeset/config.json):
@core-ai/core-ai@core-ai/opentelemetry@core-ai/axiom@core-ai/langfuse@core-ai/openai@core-ai/openai-compat@core-ai/anthropic@core-ai/google-genai@core-ai/google-vertex@core-ai/mistral@core-ai/azure-openai@core-ai/omnifact@core-ai/anthropic-vertex@core-ai/kimi
Selecting any one package in a changeset bumps every package in the fixed group to the same version. Create a changeset for every package with meaningful changes — use separate files when the changelog text differs per package.
Changeset scope and granularity
Use this decision table:
| Situation | Files | Frontmatter | Body |
|---|
| Independent provider changes (new package, provider-specific API, new models, internal updates) | One file per package | One package each | Scoped to that package only — never mention other provider packages |
Uniform cross-package change (shared interface, method signature, config tweak in @core-ai/core-ai) | One file | Multiple packages OK | Same text applies to all listed packages |
| Multi-package PR with different changes per provider | Multiple files | One package per file | Each file has its own scoped body |
Additional rules:
- One changeset per logical change. If core types and provider adapters change for different reasons, use separate changesets.
- Provider changes: Use one changeset file per provider when changes are independent. A coordinated refactor across providers (e.g. new
openai.chat API, new @core-ai/openai-compat package, Azure v1 Responses default, Omnifact wiring) still counts as independent — split the changesets.
- Cross-provider changes: Use a single changeset with multiple packages in the frontmatter only when the identical changelog text is correct for every listed package.
- Do not combine independent provider changes into one file — the body is duplicated verbatim into every listed package's changelog.
Empty changesets
For changes that don't affect published packages (CI, internal tooling, docs, tests):
npx changeset --empty
The release automation requires a changeset on every PR to function correctly.
PR Conventions
Pre-merge checklist
Before opening or updating a PR, verify:
- Code changes are complete and tested
npm run release:check passes (build + lint + types)- Changeset file is included
- PR description explains what and why
Typical flow
git checkout -b feat/my-feature main
git add . && git commit -m "implement feature X"
npm run changeset
git add .changeset/ && git commit -m "add changeset"
git push -u origin feat/my-feature
After review, merge to main (squash or merge commit).
Quick Reference
| Task | Command / Action |
|---|
| Start feature | git checkout -b feat/name main |
| Add changeset | npm run changeset |
| Empty changeset | npx changeset --empty |
| Validate before merge | npm run release:check |
