Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
111 lines (79 loc) · 4.52 KB

CONTRIBUTING.md

File metadata and controls

111 lines (79 loc) · 4.52 KB

Contributing to squeez

License + Contributor sign-off

squeez is licensed under Apache License 2.0 (see LICENSE).

Every contribution must be signed off under the Developer Certificate of Origin (DCO) 1.1. Signing off is a trailer in every commit:

Signed-off-by: Your Real Name <your.email@example.com>

The easy way — add -s to every commit:

git commit -s -m "your commit message"

Or configure git once per clone to always sign off:

git config --local format.signoff true

The signoff is a lightweight affirmation that you wrote (or have the right to contribute) the patch under the project's license. It's not a CLA — there's no separate document to sign, and you keep the copyright on what you contribute.

A DCO workflow check blocks any PR whose commits lack a valid Signed-off-by: line until it's added.

Releases

How the release pipeline works

  1. Every merge to main triggers release-please.yml, which opens or updates a "Release PR" at the top of the PR list. The PR title is always chore(main): release X.Y.Z.
  2. Merging the Release PR causes release-please to tag the repo (vX.Y.Z) and push the tag using RELEASE_PAT. That tag push triggers release.yml, which builds platform binaries (macOS universal, Linux x86_64/aarch64 musl, Windows MSVC), runs smoke tests, publishes the GitHub Release, then publishes to npm and crates.io.
  3. CHANGELOG.md is auto-managed by release-please — do not edit it by hand except through the Release PR. Sections are generated from conventional commit messages.

Conventional commit bump rules

Prefix Version bump
feat: minor
fix: / perf: patch
feat!: / fix!: / BREAKING CHANGE: in body major
chore: / docs: / test: / ci: / refactor: no bump (no release)

Prerelease / @next dist-tag

When a tag contains a prerelease identifier (e.g. v2.0.0-alpha.1, v2.0.0-beta.2, v2.0.0-rc.1), release.yml publishes to npm with --tag next instead of --tag latest. To opt into prereleases:

npm install squeez@next

To configure release-please to generate prerelease tags, set "prerelease": true and "prerelease-type": "alpha" (or beta/rc) in release-please-config.json. Currently disabled — "prerelease": false.

GPG signed tags (optional)

By default tags are unsigned. To enable signed tags:

  1. Generate a key: gpg --full-generate-key
  2. Export the public key: gpg --armor --export KEYID → add to your GitHub profile under Settings → SSH and GPG keys
  3. Add the private key to repo secrets as RELEASE_GPG_PRIVATE_KEY
  4. Add the passphrase to repo secrets as RELEASE_GPG_PASSPHRASE
  5. Configure git locally: 
    git config --global user.signingkey KEYID
git config --global commit.gpgsign true
git config --global tag.gpgSign true
  6. Uncomment the GPG import block inside .github/workflows/release-please.yml (see the comments there).

Adding a new command handler

  1. Create src/commands/newcmd.rs implementing Handler trait
  2. Write tests in tests/test_newcmd.rs
  3. Add a real fixture: bash bench/capture.sh "newcmd args" > bench/fixtures/newcmd.txt
  4. Register in src/commands/mod.rs and src/filter.rs
  5. Run: cargo test && bash bench/run.sh
  6. Open a PR

Adding a fixture

bash bench/capture.sh "your command" > bench/fixtures/your_command.txt

Testing the MCP server

The MCP server (squeez mcp) is tested via tests/test_mcp_server.rs — these tests call handle_request() directly without a running process. To exercise the wire protocol end-to-end:

echo '{"jsonrpc":"2.0","id":1,"method":"initialize"}' | ./target/release/squeez mcp

When adding new MCP tools, add them to:

  • src/commands/mcp_server.rs — handle_tools_list() and handle_tools_call()
  • src/commands/protocol.rs — mention in SQUEEZ_PROTOCOL (the auto-teach payload)
  • tests/test_mcp_server.rs — at minimum a tools/list check

Context engine changes

Changes to src/context/ should be tested against the 16-call sliding window edge cases. Key invariants:

  • Exact-hash dedup: RECENT_WINDOW = 16, MIN_LINES = 2
  • Fuzzy dedup: MIN_LINES_FUZZY = 6, Jaccard ≥ SIMILARITY_THRESHOLD = 0.85, length ratio ≥ LENGTH_RATIO_GUARD = 0.80
  • Adaptive intensity: Full below 80% of budget(cfg), Ultra above. Budget = compact_threshold_tokens × 5/4
  • Benign summarize: BENIGN_MULTIPLIER = 2, threshold doubled when no error markers found