Skip to content

[Feature Request] Add a CONTRIBUTING.md consolidating the de-facto contribution rules #603

Description

@axisrow

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.

Activity

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions