Skip to content

Guides

Contribute

Choose a contribution, prepare evidence and find the guide for your task.

Where to start

Start new features in GitHub Discussions. Report bugs in an issue with the command, actual output and version. Documentation and small fixes can go straight to a PR. Check existing issues and the roadmap first; comment on an issue before picking it up.

Prepare a verifiable change

The PR states the problem, the change, the proof, the baseline and the risk, and uses the agent section to say when an agent wrote part of the diff. Paste the real command output. Run the failing command on the current main to separate a regression from earlier debt; a behavior change needs a test that failed before and passes now. Using ork is recommended and optional. The maintainer merges with the required checks green on the exact commit and handles publishing.

CI runs the database-free suite, the package and the OpenClaw plugin; it does not run integration tests, ruff or mypy. Integration tests erase the test database and only accept a target with test, _ci or sandbox in its name, in ORKMIND_TEST_DATABASE_URL and ORKMIND_PROVIDER_TEST_DATABASE_URL. Run them when you change anything that writes to the database and say in the PR what you ran.

python -m pip install -e ".[dev,memory-provider,documents,qdrant,encryption]"
python -m pytest -m "not integration" -q

One guide per task

OrkMind has one guide per task in docs/contribuir, indexed in CONTRIBUTING: from cloning to tests, documentation, style, pull requests, triage and publishing. Each guide opens with a one-sentence answer, and a test checks that the commands, paths and links it cites exist.

The guides are in Brazilian Portuguese today; an English version is planned before launch. Clear contributions in English are welcome.

In Orkastery and with ork

To contribute to Orkastery, or to drive your contribution with ork, use the Orkastery guides. The core's full suite runs without the optional dependencies: a test that needs them is skipped with the reason, and ORK_TESTE_EXIGE_AMBIENTE=1 skips nothing. CI requires a CHANGELOG line when the PR changes core, adapters or marketplaces, and each thread's proof bundle lives in .ork-ci/<thread>.json.

Response time, review and security

The target is an initial response to issues within 7 days, and an initial PR review within the same period. This is a target, not a guarantee. If it is missed, comment on the original request. Report vulnerabilities through the private channel in SECURITY.md. Keep secrets, personal information and customer data out of the repository.