Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
97 lines (73 loc) · 3.64 KB

CONTRIBUTING.md

File metadata and controls

97 lines (73 loc) · 3.64 KB
Raw

Contributing to openapi-to-rust

Thanks for helping make real-world OpenAPI documents easier to use from Rust. Bug reproductions with a small schema are especially valuable: generated-code problems are much faster to review when the wire shape is visible in a fixture.

Before you start

  • Use GitHub Discussions for usage questions and design exploration.
  • Use the issue forms for reproducible bugs and concrete feature requests.
  • For a larger generated-API or configuration change, open an issue before investing in an implementation so compatibility tradeoffs can be discussed.
  • Follow the Code of Conduct and report vulnerabilities through SECURITY.md, not a public issue.

Development setup

The project requires Rust 1.88 or newer, Git, and Bash. Clone with submodules so the vendored JSON Schema conformance corpus is available:

git clone --recurse-submodules https://github.com/gpu-cli/openapi-to-rust.git
cd openapi-to-rust
cargo test

External contributors do not need the maintainers' Beads issue-tracking tool. Reference the public GitHub issue in your pull request when one exists.

Repository map

  • src/analysis.rs converts OpenAPI schemas and operations into generator IR.
  • src/generator.rs emits models and coordinates generated files.
  • src/client_generator.rs emits HTTP/SSE client operations.
  • src/server/ emits and manages opt-in Axum scaffolding.
  • src/type_mapping.rs owns format strategies and dependency requirements.
  • tests/fixtures/ contains focused regression documents.
  • tests/conformance/ contains the compatibility catalog and reports.
  • specs/ contains the real-world corpus used by the compile gate.

Making a change

  1. Add the smallest fixture that reproduces the OpenAPI shape.
  2. Add a behavioral assertion, snapshot, or generated scratch-crate compile test. Prefer behavior assertions when a full-file snapshot would be noisy.
  3. Implement the change without hand-editing checked-in generated examples.
  4. Run the checks proportional to the change.
  5. Explain generated API or wire-format compatibility in the pull request.

For insta snapshots:

cargo insta test
cargo insta review

Review every changed snapshot. Do not accept broad snapshot churn without explaining why unrelated generated output changed.

Checks

Run the standard gate before opening a pull request:

cargo fmt --check
cargo clippy --all-features -- -D warnings
cargo test --all-features
RUSTDOCFLAGS=-Dwarnings cargo doc --no-deps --all-features

Also run the relevant distribution or corpus gate when touching these areas:

scripts/install-smoke.sh                 # packaging, CLI, or dependencies
scripts/spec-compile.sh anthropic openai # generator/client output
scripts/spec-compile.sh                  # broad generator/type changes

The full corpus generates and compile-checks 54 OpenAPI documents and can take several minutes. CI runs a fast generation tier on pull requests and the full compile tier weekly or on manual dispatch.

Compatibility expectations

Until 1.0, a minor release may correct generated Rust APIs that were incomplete or wrong on the wire. Even so, changes should be additive where practical. Call out all of the following in the pull request when applicable:

  • generated method or model signature changes;
  • serialized query, path, header, or body changes;
  • new generated runtime dependencies or features;
  • configuration migrations or default changes;
  • OpenAPI constructs that remain unsupported.

Keep commits focused and use clear imperative messages. Maintainers may squash on merge.