Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
304 lines (229 loc) · 9.54 KB

CONTRIBUTING.md

File metadata and controls

304 lines (229 loc) · 9.54 KB

Contributing to Comet

Languages: English | 中文

Thank you for helping improve Comet. This guide is meant to be practical: it explains how to set up the project, prepare a change, keep branches healthy, submit a pull request, and update project-specific assets such as skills and shell scripts.

Before You Start

  • For bug fixes, first check whether an issue or recent PR already covers the same problem.
  • For larger behavior changes, open an issue or draft PR early so the direction can be discussed before too much code is written.
  • Keep each contribution focused on one purpose. Split unrelated changes into separate PRs.
  • Include tests or explain why a change does not need tests.
  • Update documentation when behavior, commands, workflows, or user-facing text changes.

Development Setup

git clone https://github.com/rpamis/comet
cd comet
pnpm install
pnpm build

Use the Node.js and pnpm versions supported by the repository lockfile and CI. If dependency installation or build behavior differs locally, mention it in the PR.

Commands

Command Purpose
pnpm dev Watch mode (TypeScript)
pnpm build Compile TypeScript
pnpm test Run unit tests
pnpm test:coverage Run tests with coverage
pnpm test:shell Run shell script tests (requires bats)
pnpm lint Run ESLint
pnpm format Run Prettier

For shell-script work, the most useful targeted check is:

npx vitest run test/ts/comet-scripts.test.ts

Before opening or updating a PR, run the full verification command unless the change is documentation-only:

pnpm build && pnpm lint && pnpm format:check && pnpm test

Branching Model

  • master is the canonical development and release base.
  • Create task branches from the latest master.
  • Open PRs against master.
  • Merge PRs with Squash and merge.
  • Treat squashed PR branches as disposable: delete them after merge, or recreate/reset them from master before reuse.

Squash merge creates a new commit on master. If the source branch still keeps the original commits, Git cannot always recognize that both histories contain equivalent changes. Because of that, do not keep merging master back into a branch that has already been squashed.

Preparing a Change

git fetch origin
git switch master
git pull --ff-only origin master
git switch -c <type>/<short-topic>

Use a short branch name that describes the change, for example fix/dev-resync-docs or docs/contributing-guide.

While working:

  • Keep commits small enough to review.
  • Prefer adding tests before or with the implementation.
  • Run targeted tests during development.
  • Re-run formatting before the final diff.
  • Avoid broad rewrites, formatting sweeps, or unrelated metadata churn.

Keeping a PR Current

If a PR branch falls behind master, prefer rebasing your task branch onto the latest master:

git fetch origin
git switch <your-branch>
git rebase origin/master
# resolve conflicts, then run the relevant checks
git push --force-with-lease

Use --force-with-lease after a rebase because it protects remote work that you do not have locally. Avoid plain --force.

If the branch has become tangled with unrelated commits, create a clean branch from origin/master and cherry-pick only the commits that belong to the PR:

git fetch origin
git switch -c <topic>-take-2 origin/master
git cherry-pick <commit-1> <commit-2>
# run checks
git push --force-with-lease origin <topic>-take-2:<original-branch>

This keeps the PR reviewable and prevents accidental merges of unrelated work.

Shared dev Branch

If you keep a shared dev branch, use it only as a temporary working branch. After a PR from dev is squashed into master, do not merge master back into dev. Reset dev to origin/master after confirming there is no unsquashed work that still needs to be preserved:

git fetch origin
git switch dev
git status --short
git branch backup/dev-before-sync-YYYYMMDD
git reset --hard origin/master
git push --force-with-lease origin dev

If dev contains work that has not been merged to master, move that work to a new branch from origin/master before resetting dev.

Commit Conventions

Follow Conventional Commits:

<type>: <description>

Types: feat, fix, refactor, docs, test, chore, perf, ci

Examples:

docs: expand contribution workflow
fix: preserve stderr when superpowers install fails
test: cover comet state transitions

PR Process

  1. Update master and create a feature branch from it.
  2. Implement a focused change with tests.
  3. Run targeted checks while developing.
  4. Run pnpm build && pnpm lint && pnpm format:check && pnpm test before PR review, unless the change is documentation-only.
  5. Open a PR against master.
  6. Describe what changed, why it changed, and how it was verified.
  7. Respond to review feedback with follow-up commits.
  8. Use Squash and merge when the PR is approved.
  9. Delete or recreate the source branch after merge; do not keep merging master back into a squashed branch.

For documentation-only changes, run at least the relevant formatter check, for example:

npx prettier --check CONTRIBUTING.md CONTRIBUTING-zh.md README.md README-zh.md

Project Structure

src/
├── cli/index.ts       # Commander registration
├── commands/          # Command orchestrators
│   ├── init.ts        # comet init
│   ├── status.ts      # comet status
│   ├── doctor.ts      # comet doctor
│   └── update.ts      # comet update
├── core/              # Business logic (platform-agnostic)
│   ├── platforms.ts   # Platform definitions
│   ├── detect.ts      # Platform detection
│   ├── skills.ts      # Skill file operations
│   ├── openspec.ts    # OpenSpec installation
│   └── superpowers.ts # Superpowers installation
└── utils/
    └── file-system.ts # File I/O utilities

Adding a New Platform

  1. Add an entry to PLATFORMS in src/core/platforms.ts.
  2. Add the mapping to SKILLS_AGENT_MAP in src/core/superpowers.ts if it differs.
  3. Add or update tests that cover detection, installation paths, and generated instructions.
  4. Update README documentation if the platform is user-facing.

Adding or Updating a Skill

  1. Write or update the Chinese version first under assets/skills-zh/.
  2. Get the wording and behavior confirmed.
  3. Sync the English version under assets/skills/.
  4. Add new skills to assets/manifest.json.
  5. Add tests for generated assets or installer behavior when applicable.

Skill design guidance:

  • Decision Core first: Agent-facing instructions go at the top, including phase detection, dispatch logic, and error handling.
  • Reference Appendix: Field reference, script locations, and best practices go at the bottom.
  • Keep Chinese and English versions behaviorally equivalent, even when wording differs naturally.

Shell Scripts

Shell scripts live under assets/skills/comet/scripts/ and must work on macOS, Linux, and Windows Git Bash.

Rules:

  • Do not use sed -i; GNU and BSD behavior differ. Use awk for field replacement.
  • Support both sha256sum on GNU systems and shasum -a 256 on BSD/macOS.
  • Add || true to optional grep results so pipefail does not abort the script.
  • Add new scripts to the beforeEach copy list in test/ts/comet-scripts.test.ts.
  • Add new scripts to assets/manifest.json.

Script dependencies:

comet-state.sh <- comet-guard.sh, comet-handoff.sh, comet-archive.sh
comet-yaml-validate.sh <- comet-guard.sh (preflight phase)
comet-handoff.sh <- comet-state.sh (writes handoff_context/handoff_hash)

If two scripts need the same small helper, such as hashing or YAML parsing, it is acceptable to implement it independently in each script instead of forcing a shared shell library.

.comet.yaml State Changes

When changing fields in a .comet.yaml state file, update all three places:

  1. assets/skills/comet/scripts/comet-state.sh for the cmd_set whitelist and enum validation.
  2. assets/skills/comet/scripts/comet-yaml-validate.sh for schema validation and KNOWN_KEYS.
  3. test/ts/comet-scripts.test.ts for YAML examples and assertions.

Changelog

Update CHANGELOG.md for user-facing behavior changes. New version entries go at the top and the version must match package.json.

Use this shape:

## What's Changed [x.y.z] - YYYY-MM-DD

### Added

- **Feature name**: Describe what changed and why.

### Changed

### Fixed

### Tests

### Removed

### Security

Guidelines:

  • Group entries in this order: Added, Changed, Fixed, Tests, Removed, Security.
  • Start each entry with - **Bold keyword**: .
  • Describe behavior and rationale, not implementation trivia.
  • In ### Tests, summarize coverage areas instead of listing every test case.

Security

  • Scan for API keys, secrets, tokens, and private keys before publishing.
  • Keep .npmignore aligned so source-only and local configuration files are not published to npm.
  • Keep .gitignore coverage for secrets, credentials, and IDE-specific files.
  • Validate user-provided change names against path traversal before using them in filesystem paths.