Contributing to ODCS

Thank you for contributing to the Open Data Contract Standard reference implementation.

Upstream specification

Normative ODCS semantics are defined in the upstream specification. This repository's SPEC.md documents how we track and synchronize with upstream releases.

When implementing behavior:

1. Read the relevant upstream ODCS specification sections.
2. Consult docs/implementation/ for architecture and API guidance.
3. Preserve spec-aligned naming and behavior.
4. Add tests that exercise spec requirements. See docs/implementation/testing-plan.md.

Authority

The upstream ODCS specification is the single source of truth for semantics, terminology, and conformance. Implementation docs in docs/implementation/ are illustrative unless explicitly normative.

Development setup

Prerequisites

• Rust 1.75+
• Python 3.9+ (for pyodcs work)
• maturin (for Python editable installs)

Rust

git clone https://github.com/eddiethedean/odcs.git
cd odcs
cargo build
cargo test --locked

Python

python -m venv .venv
source .venv/bin/activate
pip install maturin pytest
maturin develop --features python --locked
pytest python/tests -v

Full CI parity

Run the same checks as GitHub Actions:

./scripts/check.sh

Or run individually:

cargo fmt --all -- --check
cargo clippy --all-targets -- -D warnings
RUSTDOCFLAGS="-D warnings" cargo doc --no-deps --locked
cargo test --locked
maturin develop --features python --locked
pytest python/tests -v
maturin build --features python --locked
pip install -r docs/requirements.txt
mkdocs build --strict
./scripts/check-doc-versions.sh

Code of conduct

This project follows the Contributor Covenant. Be respectful and constructive in issues and pull requests.

Implementation changes

The Rust reference crate lives in src/. Before implementing a module:

1. Read the relevant upstream specification sections.
2. Consult docs/implementation/crate-layout.md for module boundaries.
3. Preserve spec-aligned naming and behavior.
4. Add tests for behavioral changes.

Scope

The crate targets parsing, the canonical object model, validation, and diagnostics. Do not add execution, pipeline composition, or transformation features without an agreed milestone. See docs/implementation/non-goals.md.

Code style

• Run cargo fmt and cargo clippy before submitting changes.
• Keep modules aligned with docs/implementation/crate-layout.md.
• Prefer conservative behavior when the spec is ambiguous; document open questions with a TODO referencing the spec section.

Documentation

• User-facing changes: update docs/user/ and README.md.
• API changes: update docs/implementation/public-api.md.
• Breaking changes: update CHANGELOG.md
• Preview hosted docs locally: pip install -r docs/requirements.txt && mkdocs serve (published at odcs.readthedocs.io).

Pull requests

1. Describe whether the change is implementation, documentation, or infrastructure.
2. Link related issues or design discussions when available.
3. Include or update tests for behavioral changes.
4. Ensure cargo test --locked passes (and Python tests if touching bindings).

CI workflows

Workflow	Purpose
.github/workflows/ci.yml	Primary CI badge on README
.github/workflows/checks.yml	Full checks (fmt, clippy, doc, test, MkDocs)
.github/workflows/release.yml	crates.io and PyPI publish on tags

Security

Report security vulnerabilities per SECURITY.md. Do not open public issues for security-sensitive reports.

Releases

Maintainers: see docs/maintainer/releasing.md.

Questions

For ambiguous upstream spec language, open an issue with the relevant section rather than inventing behavior in code.