12f4cb4d81
Add MSRV (Minimum Supported Rust Version) pinning to 1.78 for pdftract-core and pdftract-cli. The MSRV gate prevents silent absorption of newer Rust features that would break downstream consumers on older toolchains. Changes: - CI: Add quality-matrix DAG with msrv-check step (rust:1.78-slim) - CI: Add clippy-check, fmt-check, cargo-audit, cargo-deny templates - README: Add MSRV badge (shields.io) - clippy.toml: Enable msrv=1.78 for MSRV-aware lints - CONTRIBUTING.md: Document MSRV bump policy (MINOR version event) The rust-version was already declared in workspace Cargo.toml; this bead adds the CI enforcement and documentation. Refs: pdftract-2w02
97 lines
3.7 KiB
Markdown
97 lines
3.7 KiB
Markdown
# Contributing to pdftract
|
|
|
|
Thank you for your interest in contributing to pdftract! This document covers the essential workflows for contributors.
|
|
|
|
## Minimum Supported Rust Version (MSRV)
|
|
|
|
The **Minimum Supported Rust Version (MSRV)** for pdftract is **1.78**. This is the oldest Rust version that can successfully build the project. The MSRV is declared in `Cargo.toml` via the `rust-version` field and enforced in CI.
|
|
|
|
### MSRV Policy
|
|
|
|
- **MSRV is 1.78** for the public crates (`pdftract-core`, `pdftract-cli`)
|
|
- **Bumping MSRV is a MINOR version event** — it requires at least one release of warning in the changelog
|
|
- **Never bump MSRV in a PATCH release** — this breaks downstream consumers without notice
|
|
- **CI enforces MSRV** — the `msrv-check` step builds with `rust:1.78-slim` and fails if newer Rust features are used
|
|
|
|
### When bumping MSRV
|
|
|
|
If you need to use a Rust feature newer than 1.78:
|
|
|
|
1. **Open an issue or ADR** documenting the required feature and why it's necessary
|
|
2. **Update all locations**:
|
|
- Root `Cargo.toml`: `[workspace.package] rust-version`
|
|
- CI workflow: `rust:` image tag in the `msrv-check` step
|
|
- README: MSRV badge
|
|
- `clippy.toml`: `msrv` setting
|
|
3. **Add a CHANGELOG entry** announcing the bump with at least one release of warning
|
|
4. **Wait for the next MINOR release** — never include in a PATCH
|
|
|
|
### Code review guidelines
|
|
|
|
- **New dependencies** whose declared MSRV exceeds 1.78 are rejected at code-review time
|
|
- The `msrv-check` CI step catches most MSRV violations automatically
|
|
- Reviewers should verify that new code doesn't use Rust 1.79+ features (e.g., `core::error::Error` in stable, `let-else`, certain async-fn-in-trait features)
|
|
|
|
## Lockfile Policy
|
|
|
|
pdftract uses a workspace-level `Cargo.lock` file that is **checked into version control**. This is intentional: release reproducibility requires that every build from the same commit produces byte-identical artifacts. All CI steps run with `--locked --frozen` to enforce this.
|
|
|
|
### Updating Dependencies
|
|
|
|
When adding or updating dependencies:
|
|
|
|
1. **Targeted updates (preferred):** Update a specific crate and its dependencies:
|
|
```bash
|
|
cargo update -p crate-name
|
|
```
|
|
|
|
2. **Full updates:** Only during release preparation:
|
|
```bash
|
|
cargo update
|
|
```
|
|
|
|
3. **Commit the lockfile:** Always commit `Cargo.lock` alongside any `Cargo.toml` changes:
|
|
```bash
|
|
git add Cargo.toml Cargo.lock
|
|
git commit -m "deps: upgrade crate-name to X.Y.Z"
|
|
```
|
|
|
|
### CI Enforcement
|
|
|
|
- The `pdftract-ci` Argo workflow runs `cargo check --locked --frozen` as the first step.
|
|
- A PR that edits `Cargo.toml` without updating `Cargo.lock` will fail CI.
|
|
- Two consecutive builds of `pdftract-build-binaries` against the same tag must produce identical binaries (verified by SHA256 comparison).
|
|
|
|
### Why Library Crates Have Cargo.lock
|
|
|
|
The Rust ecosystem convention is that library crates should not check in `Cargo.lock`, allowing downstream consumers to resolve their own dependency versions. pdftract departs from this convention because:
|
|
|
|
- **Release reproducibility** is paramount for SLSA Level 3 provenance.
|
|
- The workspace produces both libraries (`pdftract-core`) and binaries (`pdftract-cli`, `pdftract-py`).
|
|
- A single workspace-level `Cargo.lock` applies to all members.
|
|
- Downstream consumers can still ignore the lockfile by using `cargo build --frozen` with their own lockfile, or by vendoring.
|
|
|
|
## Development Workflow
|
|
|
|
### Building
|
|
|
|
```bash
|
|
cargo build --release
|
|
```
|
|
|
|
### Testing
|
|
|
|
```bash
|
|
cargo test --all
|
|
```
|
|
|
|
### Linting
|
|
|
|
```bash
|
|
cargo clippy --all-targets --all-features
|
|
cargo fmt --check
|
|
```
|
|
|
|
## Security
|
|
|
|
This project uses `cargo-audit` and `cargo-deny` for supply-chain security. New direct dependencies require an ADR or written justification in the PR description.
|