Skip to content

Find code by asking what it does. A CLI for coding agents that uses Jev to discover relevant files and source context.

docs: define contribution and PR review policy

David Zhangb9d24fca0eee
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
new file mode 100644
index 0000000..e14347d
--- /dev/null
+++ b/CONTRIBUTING.md
@@ -0,0 +1,55 @@
+# Contributing
+
+Jevgrep is maintained as a small, dependable tool for coding agents. A pull
+request should make the product easier to use or maintain without creating a
+new standing obligation for every future release.
+
+## Before opening a pull request
+
+Start from current `main` and keep one change in one pull request. Explain the
+user-facing contract, the reason for the change, and the checks that support
+it. Keep measurements honest: identify the fixture, provider, and limits of a
+benchmark instead of presenting a local result as a general guarantee.
+
+Use an existing extension point before adding a new one. In particular, custom
+provider endpoints are the path for additional compatible backends; adding a
+built-in provider needs a clear maintenance benefit that custom endpoints
+cannot provide.
+
+## How pull requests are reviewed
+
+Review starts with the contract at the boundary the change touches: command
+output, provider requests, cache entries, packaged files, or a module API. The
+implementation should have one clear owner for each concept and should remove
+obsolete paths when it replaces them.
+
+A change is a good merge candidate when it solves a real user or maintenance
+problem, is focused, current with `main`, covered by behavior-level tests, and
+does not add avoidable configuration, release, provider, or operational
+maintenance. A merge conflict is an integration task, not a reason to reject
+an otherwise valuable change. Reviewers should rebase or port the change before
+deciding its product value.
+
+Reviewers run the narrowest check that proves the change, then the full
+verification described in the [development guide](README.md#development) when
+the complete slice is ready. Release and package changes also follow [the
+release guide](scripts/RELEASING.md).
+
+Reviewers request changes when the idea fits but the contract, tests, failure
+behavior, or maintenance cost is not yet clear. They close a pull request when
+it is spam, duplicates an existing capability, expands the default surface
+without a durable need, requires new account or deployment configuration, or
+adds more long-term complexity than the problem justifies.
+
+## What a merged change must leave behind
+
+- The behavior and failure modes are pinned by tests that exercise the product
+ contract rather than implementation details.
+- The user-facing output is checked directly when output changes.
+- Documentation explains the principle and points to the code that owns the
+ current details; it does not copy command matrices or file inventories.
+- The repository remains installable and releasable through the existing path.
+
+Contributors do not need to solve unrelated cleanup in the same pull request.
+Small, well-scoped changes are easier to verify and less likely to become
+maintenance debt.
diff --git a/README.md b/README.md
index 0700706..8cf9968 100644
--- a/README.md
+++ b/README.md
@@ -167,4 +167,7 @@ reasoning behind retrieval, parsing, caching, and failure handling, start with t
[Release guidance](scripts/RELEASING.md) covers tag-triggered npm publication and
verification of the exact public package.
+See [Contributing](CONTRIBUTING.md) for the pull-request review and maintenance
+policy.
+
[MIT](LICENSE). [Artwork and generation prompts](assets/README.md).