Autonomous research system for measurable, computer-executable research.
Python
docs: define contribution validation workflow (#185)
electrixoulbe6233e76d62
diff --git a/docs/guides/contributing.md b/docs/guides/contributing.mdindex cd24b15..7b97c44 100644--- a/docs/guides/contributing.md+++ b/docs/guides/contributing.md@@ -1,35 +1,85 @@# Contributing-This repository is edited by both humans and agents. The durable rule is simple:-keep system code, generic plugins, task templates, complete examples, and real-task projects physically separate.+Praxist welcomes bug reports, improvement ideas, documentation fixes, and code+contributions. Contributors only need to open an issue or pull request; the+maintainer team takes responsibility for integration, full verification, and+real-task validation before a change reaches `main`.-## Read First+## Submit an Issue or Pull Request-- `AGENTS.md` is the machine-friendly repository contract.-- `docs/concepts/architecture.md` is the active architecture overview.-- `docs/index.md` is the source documentation entry.+An issue should explain the observed behavior, the expected behavior, and any+reproduction evidence that can be shared safely.-## Default Change Flow+A pull request should answer four questions:-1. Identify whether the change belongs to core, a generic plugin, a task template,- a complete example, an external task project, tests, docs, or operator scripts.-2. Make the smallest change that fits the existing boundary.-3. Add or update tests at the same boundary.-4. Rebuild docs when docstrings or docs changed.-5. Record high-risk architectural implementation context in the commit or- pull-request description.+1. What changed?+2. Why is the change needed?+3. How can the behavior be checked?+4. Is there anything maintainers should know about compatibility or risk?-## Stable Docstrings+Focused tests are appreciated when practical, but contributors are not expected+to run paid model calls, multi-generation research tasks, or the complete CI+matrix. Draft pull requests are welcome when early feedback would help.-Public and semi-public Python APIs use Google-style docstrings. A docstring-should describe the contract that future callers can rely on, not the history of-one bug fix.+## Work With the Architecture-Use comments for non-obvious invariants, recovery behavior, and failure policy.-Do not add comments that only restate the next line of code.+Praxist separates framework code, generic plugins, task templates, complete+examples, and external task projects. Where practical, we ask contributors to+follow these existing boundaries so changes remain reusable across research+domains. The maintainers will help adapt a sound contribution when repository+conventions are unfamiliar.-## Default Verification+Before making a substantial change, please consult:++- `AGENTS.md` for the machine-friendly repository contract;+- `docs/concepts/architecture.md` for the active architecture; and+- `docs/index.md` for the documentation source map.++Keep changes focused, avoid task-specific assumptions in shared code, and update+tests and documentation at the affected boundary.++## What Happens After Submission++1. **Review.** Maintainers examine each open issue and pull request for+ correctness, scope, compatibility, and overlap with other contributions.+2. **Integration.** Issue fixes are prepared on maintainer-owned validation+ branches. Closely related pull requests may be combined on one+ `validation/<topic>` branch so their interaction can be tested together.+3. **Automated verification.** The selected implementation receives focused+ tests, the full test suite, and local CI. The validation branch is frozen at+ an exact commit while evidence is collected.+4. **Real-task validation.** Changes that can affect runtime or research+ behavior are exercised on representative task projects. This commonly takes+ one to three days because the team also checks generation-level performance+ trends and research-loop integrity.+5. **Merge.** A validated branch is reconciled with the current `main`, checked+ again, merged, and then deleted. A branch that exposes a regression returns+ to implementation and validation instead.++Documentation-only and similarly isolated changes can use a faster path when+they cannot affect runtime behavior. The maintainer team runs at least one+review and validation cycle each week; validated changes are merged as soon as+they are ready.++## Pull Request Transfer and Credit++When a contribution moves to a maintainer-owned validation branch, the original+pull request may be closed after a maintainer links the destination branch and+commit. This means the contribution has entered validation, not that it was+rejected.++Original commits are retained when suitable. If maintainers need to combine or+adapt overlapping implementations, contributor credit is preserved with+recognized co-author attribution. The related issue remains available for+validation updates, findings, and the final outcome.++## Verification Responsibilities++Contributors should run the narrow checks they can reasonably run and state what+was not tested. Praxist automation and maintainers are responsible for the full+merge gate, platform checks, integration work, and any costly task runs.++For contributors who want to run the same repository checks locally:```bashuv sync --group dev --extra docs@@ -41,22 +91,18 @@ uv run python scripts/build_docs_site.pygit diff --check```-Narrow changes can start with narrow tests, but the default handoff should still-include the full suite above.--The coverage command writes ignored local reports under `cover/unit/` and-`cover/integration/`. The `unit` profile is the offline non-integration test-layers and is held at 90% branch-aware total coverage plus 95% statement-coverage; the `integration` profile is `tests/integration` and remains-observational. It uses `coverage.py` from the dev dependency group and keeps the-test runner on `unittest`.+Coverage reports are written to the ignored `cover/unit/` and+`cover/integration/` directories.-## What Requires Extra Care+## Changes That Need Extra Care-Extra care is required when changing startup, plugin resolution, task path-resolution, credential selection, runtime invocation, prompt layout, event-driven-peer scheduling, finding graph guidance, budget policy, replay verification, or-run artifact schemas.+Changes to startup, process ownership, plugin resolution, task paths,+credentials, runtime invocation, prompt layout, peer scheduling, Finding Graph+guidance, budgets, replay verification, research retention mechanisms, or run+artifact schemas can affect unrelated task projects. These changes require+focused contract tests and maintainer-run task validation before merge.-Those changes should include focused tests and, when they change architecture-contracts, a concise rationale in the pull-request description.+Public and semi-public Python APIs use Google-style docstrings. Describe the+contract that callers can rely on, rather than the history of one fix. Comments+should explain only non-obvious invariants, recovery behavior, or failure+policy.