Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
40 lines (29 loc) · 4.23 KB

CONTRIBUTING.md

File metadata and controls

40 lines (29 loc) · 4.23 KB
Raw

Contributing to pharn

Thanks for your interest in improving PHARN. This repository is pharn — the ESM-only Node CLI that installs PHARN capabilities from pharn-dev/pharn-oss into a project — under .claude/ and pharn/, plus THREAT-MODEL.md, LIMITS.md, pharn/features/README.md, pharn.config.json and pharn.records.json at the project root. The full contributor guide lives in docs/contributing.md — start there.

Read first

Before changing anything, read these in order:

  1. CLAUDE.md — how the CLI works and its hard constraints (the architecture source of truth: the archetype install flow, capability resolution, and the security-sensitive libs).
  2. README.md — what the CLI is and how it's run.
  3. docs/contributing.md — the full development guide (setup, quality gates, test map, doc maintenance).

Quick links

  • How to contribute → docs/contributing.md (setup, quality gates, branch naming, commit style, test map, doc maintenance)
  • Where your change goes → CLAUDE.md architecture section and the test map
  • The rules of the repo → CLAUDE.md (source of truth — read it before adding, editing, or removing anything)
  • User-facing docs → docs/
  • Releasing (maintainers) → docs/RELEASING.md (version bump → GitHub Release → npm via Trusted Publishing)
  • Community standards → CODE_OF_CONDUCT.md

The 30-second version

  1. Open an issue first for any non-trivial change. PHARN is small-surface on purpose.
  2. Install: cd pharn-cli && npm install (dev-only tooling; only dist/ ships to npm).
  3. Run the gates before pushing. CI runs six, each as its own job, and all six are required status checks on main (alongside floor, gitleaks and Analyze (javascript-typescript), for nine in total): npm run format:check · npm run lint · npm run lint:md · npm run typecheck · npm run test:coverage · npm run build npm run check runs the first four plus test, so it is the one command to reach for — but it is not the whole of CI: it skips build, and it runs test rather than test:coverage, so it does not enforce the coverage thresholds. See the gates table for the job names.
  4. Branch: feat/…, fix/…, or docs/….
  5. Commit in Conventional Commits style, one logical change per commit — and write the PR title the same way. PRs are squash-merged, so the PR title becomes the commit message on main; individual commit messages inside the branch are discarded. Nothing enforces this automatically, so it is a reviewer check: main carries at least one changes (#97) that landed a real behaviour change under the least informative possible message.
  6. Tests first — when changing behavior, update the matching tests/*.test.ts before touching code. The suite mirrors commands/, steps/ and lib/ one-to-one, with lib/hash.ts the single exception.
  7. Security-sensitive files (lib/validate.ts, lib/install-capabilities.ts, lib/skills-version.ts, lib/tar-extract.ts, lib/repo.ts) — preserve the validation invariants (regex/enum allowlists, safeJoin path guard, symlink rejection, redirect: 'error', and the fetch timeout/size caps) called out in CLAUDE.md.
  8. Keep docs in sync — see the Documentation maintenance table.

Conduct and security

  • Be a good citizen — this project follows our Code of Conduct. By participating, you are expected to uphold it.
  • Found a vulnerability? Do not open a public issue, discussion, or PR — follow the private disclosure process in SECURITY.md. The CLI sits at a trust boundary (it fetches remote content and writes it into a user's project), so security reports go through coordinated disclosure.

By contributing, you agree your contributions are licensed under the repository's Apache 2.0 license.