Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
132 lines (94 loc) · 4.76 KB

CONTRIBUTING.md

File metadata and controls

132 lines (94 loc) · 4.76 KB
Raw

Contributing to openclaw-engram

Thanks for contributing. We welcome both issues and pull requests from humans and AI-assisted contributors.

Ways to contribute

  • Report bugs via GitHub Issues
  • Propose features via GitHub Issues
  • Submit pull requests for fixes, docs, tests, and improvements
  • Improve examples/docs to help adoption

Before opening a PR

  1. Search existing issues/PRs to avoid duplicates.
  2. For non-trivial changes, open an issue first and propose approach/scope.
  3. Keep changes focused and small when possible.

Development setup

Requires Node.js >=22.12.0 (aligned with OpenClaw engine support).

npm ci
npm run check-types
npm test
npm run build

Install local guard hooks (recommended):

npm run hooks:install

This enables:

  • pre-commit: npm run preflight:quick
  • pre-push: npm run preflight

Cursor headless review behavior (npm run review:cursor):

  • Runs only if agent (preferred) or cursor-agent is installed and callable.
  • Auto-skips (non-failing) when Cursor CLI is unavailable/unconfigured.
  • Returns non-zero when it reports findings in strict finding format.
  • Uses documented print mode (-p) with --output-format text in non-interactive flow.
  • Override knobs:
    • CURSOR_PREPUSH_MODEL=<model> to pick model (default: auto).
    • CURSOR_PREPUSH_BASE_REF=<ref> to change diff base (default: origin/main).
    • CURSOR_PREPUSH_TIMEOUT_SECONDS=<seconds> to control headless review timeout (default: 300).
    • CURSOR_PREPUSH_MAX_DIFF_CHARS=<chars> to cap diff included in prompt (default: 120000).
    • CURSOR_PREPUSH_STRICT=1 to fail when Cursor is unavailable/timed-out/unparseable (recommended for maintainers running manual pre-push review).

Install path for users

Use npm install via OpenClaw as the primary install path in docs:

openclaw plugins install openclaw-engram --pin

PR quality bar

A good PR should:

  • Include tests for behavior changes
  • Keep backwards compatibility unless intentionally changed
  • Avoid unrelated refactors in the same PR
  • Update docs for user-facing/config changes
  • Update CHANGELOG.md (see changelog policy below)

For retrieval/planner/cache/config changes, run the mandatory hardening gate:

  • docs/ops/pr-review-hardening-playbook.md

Changelog policy

This repository uses CHANGELOG.md on main as the contributor-facing ledger for upcoming release notes. Published per-version notes ship through GitHub Releases from the tagged release workflow.

  • Add a concise entry in ## [Unreleased] for user-facing changes.
  • Use one of the standard sections when possible: Added, Changed, Fixed, Security.
  • Keep entries short and outcome-focused.

A CI check enforces Unreleased changelog updates when source/config files change. Maintainers can bypass for exceptional cases by applying label skip-changelog.

AI-assisted contributions

AI-assisted and agent-assisted PRs are welcome.

Please ensure:

  • A human reviews and stands behind the final PR
  • Generated code is understood, minimal, and tested
  • No secrets, tokens, or private data are introduced
  • Tooling or automation changes include clear rationale

Security

  • Do not submit secrets in code, issues, or PRs.
  • If you find a sensitive vulnerability, open a private security report where possible instead of posting exploit details publicly.

Review and merge process

  • Maintainers may request changes for scope, safety, tests, and documentation.
  • PRs require passing checks and at least one maintainer approval.
  • Significant changes may be merged in follow-up slices to reduce risk.
  • For logic changes in retrieval/planner/caching, reviewers should verify:
    • flag symmetry (enabled=false disables write+read effects)
    • zero semantics (0 is never coerced to 1)
    • cap-after-filter behavior
    • cache coherence across instances/concurrency
    • fallback parity (same policy constraints as primary and fallback paths)
    • artifact isolation (artifacts/ excluded from generic memory recall path)
    • planner mode reachability (no_recall, minimal, full, graph_mode)
    • heuristic robustness (intent patterns cover common language variants)

Release process

  • Merges to main trigger an automated release workflow.
  • The workflow validates (check-types, test, build), bumps a patch version, tags vX.Y.Z, creates a GitHub release, and publishes to npm.
  • Configure repository secret NPM_TOKEN (npm automation token) for publish.
  • If NPM_TOKEN is missing, release creation still runs but npm publish is skipped.

Good first contributions

Useful high-impact contributions include:

  • Better error messages and docs
  • Additional regression tests
  • Example configs for common providers
  • Performance/safety improvements with benchmarks/tests

Thanks again for improving openclaw-engram.