9aa26a449e
This commit implements the Cargo.lock policy for reproducible builds across all workspace members (pdftract-core, pdftract-cli, pdftract-py). Changes: - Add CONTRIBUTING.md with lockfile-update workflow documentation - Add .renovaterc.json for weekly lockfile-only PRs (human-gated) - Add crates/pdftract-core/README.md with rationale for checked-in lockfiles - Add notes/pdftract-49f8.md with verification note The Argo workflow updates (pdftract-ci.yaml) are committed separately in the declarative-config repo. Acceptance criteria: - PASS: Cargo.lock tracked by git, not in .gitignore - PASS: Argo workflow templates document --locked/--frozen requirements - WARN: Enforcement to be completed when placeholder templates are implemented - WARN: Binary reproducibility verification deferred to pdftract-build-binaries implementation Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
67 lines
2.2 KiB
Markdown
67 lines
2.2 KiB
Markdown
# Contributing to pdftract
|
|
|
|
Thank you for your interest in contributing to pdftract! This document covers the essential workflows for contributors.
|
|
|
|
## 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.
|