Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
79 lines (57 loc) · 3.46 KB

CONTRIBUTING.md

File metadata and controls

79 lines (57 loc) · 3.46 KB
Raw

Contributing

Contributions are welcome when they preserve the repository's central constraint: completeness is a set of explicit, contextual decisions rather than a universal feature checklist.

Local setup

Requirements: Node.js 22.22 or newer. Maintainer and CI runs use Node.js 24.19.0 with npm 11.4.1; .nvmrc selects the pinned baseline.

On POSIX shells, install with the required ONNX postinstall guard:

ONNXRUNTIME_NODE_INSTALL=skip npm ci --include=optional
npm run validate
npm run validate:promptfoo

On PowerShell, use the equivalent scoped environment variable:

$env:ONNXRUNTIME_NODE_INSTALL = "skip"
npm ci --include=optional
Remove-Item Env:ONNXRUNTIME_NODE_INSTALL
npm run validate
npm run validate:promptfoo

The normal pull-request gate is deterministic and does not require model credentials. npm run check:links performs the separate network-dependent source check; CI reports its failures as advisory so an upstream outage cannot block a change.

Accepted optional dependency risk

The pinned maintainer tree currently reports five high-severity dependency nodes representing two optional transitive advisories under promptfoo -> @huggingface/transformers -> onnxruntime-node. The adm-zip path is reachable only during the ONNX native-binary postinstall, which the required ONNXRUNTIME_NODE_INSTALL=skip guard disables. This repository does not use Hugging Face providers, Transformers, or ONNX. Optional packages remain enabled because Promptfoo's libSQL runtime needs its platform-specific optional dependencies. The published skills do not ship this private maintainer package or its development dependencies.

Do not apply npm audit fix or dependency overrides for this accepted path: either can silently change the pinned Promptfoo graph or remove the optional libSQL packages required by the evaluation harness. Reassess the exception when Promptfoo removes or upgrades the affected optional chain.

Change a rule

  1. Edit the canonical files under knowledge/; never hand-edit generated capability catalogs.
  2. Give the rule a stable ID, authority, strength, applicability and skip conditions, exceptions, source IDs, verification steps, verification date, and target skills.
  3. Run npm run generate:references and commit the generated files inside each affected skill.
  4. Add or update a synthetic scenario when behavior changes.

Use must only for a genuine standard, security boundary, or correctness invariant. Product conventions normally use must-decide, should, or may.

Change a skill

  • Keep SKILL.md concise and route conditional detail to a directly linked reference.
  • Put both positive and negative invocation boundaries in the frontmatter description.
  • Preserve the public output states documented in the README.
  • Add routing cases for both sides of every changed trigger boundary.
  • Keep all runtime references inside the individual skill directory so single-skill installation works.

Fixtures

Fixtures must be synthetic. Do not copy customer data, internal project code, private names, credentials, or proprietary schemas. Add machine-readable expectations and at least one forbidden overbuilding outcome.

Pull requests

Use a focused title and explain:

  • the observed failure or missing capability
  • the authority for the change
  • why the applicability boundary is narrow enough
  • which routing and scenario cases prove it

By contributing, you agree that your contribution is licensed under the MIT License.