Contributing to Clank

Clank favors small public contracts, explicit security boundaries, deterministic behavior, and platform primitives over hidden dependency machinery.

#Before changing code

Open an issue for a new public API, wire protocol, persistent schema, authentication behavior, deployment state transition, or compatibility break. A short proposal should contain:

1. the human and agent workflow;
2. the smallest proposed contract;
3. authorization and data boundaries;
4. migration and rollback behavior;
5. alternatives considered; and
6. the evidence that will prove the change works.

Typographical fixes, tests for existing behavior, and narrow bug fixes do not require a proposal.

#Development

Requirements:

• Node 22.16 or newer;
• no runtime or development NPM dependencies; and
• a filesystem that supports normal SQLite locking and atomic rename semantics.

Run:

npm run check

That command builds the framework, enforces the zero-dependency and coverage contracts, audits documentation/declaration/package-export integrity, runs unit/integration tests, installs and exercises the packed release through the complete conformance journey, and finishes with package/tree/history security checks.

#Pull requests

• Add tests that would fail without the change.
• Update every relevant public guide and API reference.
• Preserve the zero-dependency contract.
• Keep generated files, databases, credentials, .env files, platform state, and local artifacts out of commits.
• Explain compatibility, migration, failure recovery, and rollback.
• Treat model output, browser input, uploaded artifacts, migrations, URLs, and persisted application data as untrusted.

Large modules may be split when the split improves a concrete change. Moving code without improving a public boundary, testability, or security property is not itself a goal.

#Commit and release policy

Maintainers use reviewed pull requests for main. Releases follow the release process. By contributing, you agree that your contribution is licensed under the repository's MIT license.

Git commit author and committer addresses are public repository metadata. Contributors who want email privacy should configure GitHub's account-specific ID+username@users.noreply.github.com address locally and enable GitHub's command-line push protection for personal email addresses before committing. Never rewrite published shared history only to change an address; coordinate any history rewrite as a separate incident response when actual credentials or regulated data were committed.