{"protocol":"clank-doc/1","frameworkVersion":"0.8.0","slug":"contributing","title":"Contributing to Clank","description":"Clank favors small public contracts, explicit security boundaries, deterministic behavior, and platform primitives over hidden dependency machinery.","group":{"id":"project","title":"Project"},"url":"https://docs.clank.run/docs/contributing","source":"CONTRIBUTING.md","headings":["Before changing code","Development","Pull requests","Commit and release policy"],"tableOfContents":[{"id":"before-changing-code","title":"Before changing code","level":2},{"id":"development","title":"Development","level":2},{"id":"pull-requests","title":"Pull requests","level":2},{"id":"commit-and-release-policy","title":"Commit and release policy","level":2}],"markdown":"# Contributing to Clank\n\nClank favors small public contracts, explicit security boundaries, deterministic behavior, and platform primitives over hidden dependency machinery.\n\n## Before changing code\n\nOpen an issue for a new public API, wire protocol, persistent schema, authentication behavior, deployment state transition, or compatibility break. A short proposal should contain:\n\n1. the human and agent workflow;\n2. the smallest proposed contract;\n3. authorization and data boundaries;\n4. migration and rollback behavior;\n5. alternatives considered; and\n6. the evidence that will prove the change works.\n\nTypographical fixes, tests for existing behavior, and narrow bug fixes do not require a proposal.\n\n## Development\n\nRequirements:\n\n- Node 22.16 or newer;\n- no runtime or development NPM dependencies; and\n- a filesystem that supports normal SQLite locking and atomic rename semantics.\n\nRun:\n\n```sh\nnpm run check\n```\n\nThat 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.\n\n## Pull requests\n\n- Add tests that would fail without the change.\n- Update every relevant public guide and API reference.\n- Preserve the zero-dependency contract.\n- Keep generated files, databases, credentials, `.env` files, platform state, and local artifacts out of commits.\n- Explain compatibility, migration, failure recovery, and rollback.\n- Treat model output, browser input, uploaded artifacts, migrations, URLs, and persisted application data as untrusted.\n\nLarge 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.\n\n## Commit and release policy\n\nMaintainers use reviewed pull requests for `main`. Releases follow [the release process](docs/releases.md). By contributing, you agree that your contribution is licensed under the repository's MIT license.\n\nGit 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.\n"}