Contribute
DDK is open source under the Apache-2.0 licence, and contributions of every
size are welcome. This page is the short version; the full runbook is
CONTRIBUTING.md
in the repository.
Ways to help
Every change starts as an issue. Search first, then file one with what you expected and what happened.
Pick up a good first issueSmall, well-scoped issues that are a good way into the codebase.
Improve the docsThis site lives in website/ (Nextra). Every page has an “Edit this page”
link.
Runnable demos live in the companion donkey-development-kit-demos
repository.
From issue to merge
File or find the issue
No change lands without a GitHub issue — the issue is the plan. Each issue carries exactly one milestone, which is the release it targets (see the Roadmap).
Cut a branch from develop
Branch names follow <type>/<issue#>-<slug>, for example
fix/42-proxy-url-trailing-slash or docs/13-verified-apis-update. Always
branch from develop; never from or into main.
git checkout develop && git pull --ff-only
git checkout -b docs/13-verified-apis-updateRun the pre-PR gate
Every CI job is a nox session of the same name, so one command runs the checks CI runs. From the repository root:
pipx install nox pre-commit # once
pre-commit install # once per clone: gitleaks, ruff, ruff format, lint-imports, and the llms regeneration (needs Node) at commit
cd python
nox -s typecheck-and-lint test-3.11 # types, lint, format, import contracts, one test leg
nox # every CI jobEach session that installs something builds its own environment and installs what its CI job installs. A Python version you don’t have is skipped, and CI still runs it. The contributor guide lists every session and what CI checks that a local run can’t.
If you touched an adapter, also run python scripts/verify_frameworks.py.
Open a pull request into develop
The PR body includes Closes #<issue#>, a ## Summary, a ## Test plan and
a ## Post-deploy steps section (write None. when nothing applies). The
repository’s PR template lays these out. PRs are squash-merged, so develop
reads as one commit per issue.
A change to an architecture invariant, an import-linter contract, the API
stability tiers or the dependency policy also needs an architecture decision
record (ADR). The template asks whether one is needed, and the process is in
docs/adr/.
Contributing from a fork
Not a member of the Donkey-Development-Kit organisation? The flow is the
same, from a fork:
git clone https://github.com/<you>/donkey-development-kit.git
cd donkey-development-kit
git remote add upstream https://github.com/Donkey-Development-Kit/donkey-development-kit.git
git fetch upstream
git checkout -b docs/13-verified-apis-update upstream/developOpen the PR from your fork into Donkey-Development-Kit:develop and tick
Allow edits by maintainers. A maintainer sets the milestone and labels,
runs the secret-gated checks that GitHub does not run on fork PRs, re-captures
any live fixture on the team sandbox before a verified-apis.md row flips,
and merges.
Keep the docs in sync
When code changes what DDK does, the docs change in the same pull request —
or a documentation follow-up issue is filed and linked. After editing pages
here, regenerate the AI-readable docs and commit the result:
cd website
npm run generate:llmsVerification discipline. DDK never documents or codes against an endpoint, header or class name that has not been confirmed against the real platform. If you can’t confirm one, say so in the issue rather than guessing — see the verification ledger .