Problem
There is no CONTRIBUTING.md in the repository. The only documented contribution guidance is the five-line "Contributing" section in the README (fork → branch → commit → push → PR). The actual expectations a PR has to satisfy are spread across AGENTS.md, docs/DEVELOPMENT.md, and CLAUDE.md (symlink), and a first-time contributor has no way to know them without reading the whole development docs.
The project clearly has de-facto contribution gates — most are visible from the release notes and code review conventions — but they are not written down as contribution rules anywhere.
Proposal
Add a short CONTRIBUTING.md (or a Contributing section in docs/) that consolidates the rules that already govern the codebase:
Workflow
- Fork → feature branch → PR (already in README).
- Run checks before opening a PR:
bun test and bun run lint must be green.
- Use
bun run lint / bun run lint:fix only — never invoke eslint/tsc directly; never disable a lint rule via a comment.
Compatibility guarantees a PR must not break
dist/ must stay compatible with Node.js 14+.
- Dual runtime (Bun + Node.js) must keep working.
- React and React DOM are exact-version pins; dependency updates change
package.json and bun.lock together.
- The
ink@6.2.0 patch (patches/) must be preserved when touching dependencies.
- Keep the macOS backspace patch rationale in mind when upgrading ink.
Testing expectations
- Vitest via Bun (
bun test); new widgets/features come with tests under src/widgets/__tests__/ / src/utils/__tests__/.
- Usage-fetch tests must be sandboxed (
HOME, USERPROFILE, CLAUDE_CONFIG_DIR, proxy vars set explicitly) so they never touch a developer's live ~/.cache/ccstatusline.
Behavioral invariants
- Settings saves stay atomic and write through symlinked
settings.json.
- Invalid/unreadable settings files are never overwritten.
- Manual verification guidance: piped-JSON mode for renderer changes, TUI for UI changes.
This would also help agent-based contributors (Claude Code and similar) — the content overlaps with AGENTS.md, but a CONTRIBUTING.md is the canonical entry point humans look for first, and AGENTS.md could simply link to it.
Problem
There is no
CONTRIBUTING.mdin the repository. The only documented contribution guidance is the five-line "Contributing" section in the README (fork → branch → commit → push → PR). The actual expectations a PR has to satisfy are spread acrossAGENTS.md,docs/DEVELOPMENT.md, andCLAUDE.md(symlink), and a first-time contributor has no way to know them without reading the whole development docs.The project clearly has de-facto contribution gates — most are visible from the release notes and code review conventions — but they are not written down as contribution rules anywhere.
Proposal
Add a short
CONTRIBUTING.md(or a Contributing section indocs/) that consolidates the rules that already govern the codebase:Workflow
bun testandbun run lintmust be green.bun run lint/bun run lint:fixonly — never invokeeslint/tscdirectly; never disable a lint rule via a comment.Compatibility guarantees a PR must not break
dist/must stay compatible with Node.js 14+.package.jsonandbun.locktogether.ink@6.2.0patch (patches/) must be preserved when touching dependencies.Testing expectations
bun test); new widgets/features come with tests undersrc/widgets/__tests__//src/utils/__tests__/.HOME,USERPROFILE,CLAUDE_CONFIG_DIR, proxy vars set explicitly) so they never touch a developer's live~/.cache/ccstatusline.Behavioral invariants
settings.json.This would also help agent-based contributors (Claude Code and similar) — the content overlaps with
AGENTS.md, but aCONTRIBUTING.mdis the canonical entry point humans look for first, andAGENTS.mdcould simply link to it.