Contributing to dctx
On this page
Read the specification, crate map and Code of Conduct before making changes. Project contributions are licensed under Apache-2.0, consistent with NOTICE.
Bugs, ideas and questions#
Search existing issues before opening one. Use the bug or feature template and keep reproductions small. Include the commit or version, OS/architecture, build features, exact command, expected result and actual result. Redact source code, paths, credentials and generated context that you do not have permission to share.
Report suspected vulnerabilities privately using SECURITY.md, rather than in an issue or pull request. For other questions, open an issue with what you tried and the relevant documentation link.
CLI development setup#
CI tests use DCTX_CI_RUST from tools/release/toolchain.env; bump it intentionally each Rust release.
Use a recent stable Rust toolchain with Cargo; the workspace includes Rust 2024 crates. Clone the repository and run commands from its root:
git clone https://github.com/Eris-Margeta/dctx
cd dctx
cargo build --locked -p dctx-cli
cargo run --locked -p dctx-cli -- --helpCargo builds dctx-cli, while help text calls the tool dctx. See
installation for aliases and install choices.
Keep changes focused on the relevant crates and preserve unrelated work. The
dctx facade serves the CLI and the desktop API; pure engine
crates should not acquire filesystem, network or process effects. The
plugin guide describes effect boundaries and current
runtime limitations.
Validation#
Start with the CLI and facade checks (some tests validate documentation):
cargo test -p dctx-cli -p dctx --lockedFor documentation changes, install the Python dependencies using
the website setup, then run
tools/website/.venv/bin/python tools/check-markdown-links.py. It checks local
paths and heading anchors across public Markdown, including HTML and reference links.
Testing documents the full Linux/macOS/Windows matrix and
local commands. The current CI workflow runs workspace
tests on stable Rust and MSRV, plus formatting, Clippy, Rust documentation,
licence, website and release checks. Run cargo fmt --all -- --check and document
public APIs. Follow Rust house style for the plugin boundaries.
When editing website source documents, regenerate website/ and check it using
the website instructions. Before committing, use
check.py --working-tree to compare your regenerated files with an independent
build; CI compares committed output. Capture CLI examples only if output changed.
Desktop changes need their platform prerequisites and separate validation; see
the desktop guide. The root just ci recipe also
invokes desktop setup and is broader than the main CI jobs.
Developer Certificate of Origin#
Contributions use the Developer Certificate of Origin (DCO) instead of a contributor license agreement. Sign off each commit to certify that you wrote the change, or otherwise have the right to submit it under Apache-2.0:
git commit -sThe -s flag adds a Signed-off-by: line with your name and email. Pull requests with
unsigned commits will be asked to amend them with git commit --amend -s, or to rebase
with --signoff.
Pull requests#
Create a focused branch from main and describe the problem, resulting behavior
and any compatibility or privacy impact. Add regression coverage for behavior
changes and update affected documentation. Check Markdown links and paths when
editing guides. Use clear commit messages, for example fix(cli): reject empty
output paths.
In the PR, list the commands you ran, their results, and any checks you could not run. Include relevant OS/build features for platform-specific changes. Avoid unrelated formatting, generated governance files, local caches, credentials and private research artifacts. Maintainers may ask for a smaller change or additional validation before merging. Pull requests, including forks, run on GitHub-hosted CI runners.