Pre Publish Check

Pre-Publish Check for dashu

Run a consistent set of checks before publishing dashu (the meta crate) or any sub-crate to crates.io. Fail loudly on any regression that would break downstream users or violate the project's release policy.

Repository context (load-bearing facts)

• The workspace contains 6 publishable crates: dashu (meta, at repo root), base/, integer/, float/, rational/, macros/. python/ is not published and is excluded from workspace commands with --exclude dashu-python.
• Major versions are always aligned across all crates (0.4.x today). Minor and patch may differ — dashu-float is at 0.4.4 while the others are at 0.4.2.
• Every crate's Cargo.toml pins the path and the version range of its dashu-internal dependencies. When sub-crate X bumps its version, every crate that depends on X (including the meta crate) must have its version requirement updated to >= the new version of X.
• The MSRV is 1.68, declared both in rust-version = "1.68" in every Cargo.toml and in the README badge (MSRV 1.68). MSRV bumps are breaking changes and require a major version bump or an explicit policy exception (see CHANGELOG history for the 1.61 → 1.68 bump pattern).
• Every crate has its own CHANGELOG.md with an ## Unreleased section. The meta dashu crate does not have a CHANGELOG — it follows the sub-crates.
• Feature-flag policy: third-party integrations are gated behind versioned feature flags (rand_v08, num-traits_v02, diesel_v2, postgres-types_v02) with an unversioned alias that points to the latest. Adding a new major-version dependency means adding a new versioned feature.
• Doc examples (# Examples blocks) on every public API are mandatory and are exercised by cargo test --doc.

Workflow

Step 1 — Identify target crate(s) and version(s)

Inspect the user's prompt for both pieces of information:

• Target crate: one of dashu, dashu-base, dashu-int, dashu-float, dashu-ratio, dashu-macros, or all.
• Target version: a SemVer string (e.g., 0.4.5, 0.5.0).

If either is missing, use AskUserQuestion to ask. Ask at most two questions in a single call:

1. "Which crate(s) are being published?" — options: each sub-crate, dashu (meta), all sub-crates + meta.
2. "What is the target version?" — leave this as free-text via the user's "Other" option, since the next version depends on what changed (major/minor/patch). Pre-populate sensible options based on the current Cargo.toml version: e.g., if current is 0.4.2, offer 0.4.3 (patch), 0.5.0 (minor — note pre-1.0 minor acts like major in SemVer), 0.4.x (let user specify).

Pre-1.0 SemVer rule for this project: since the major version is 0, a minor bump (0.4.x → 0.5.0) is the breaking-change release (acts like a major bump). A patch bump (0.4.2 → 0.4.3) only allows backward-compatible additions and fixes — no removals, no signature changes, no MSRV bumps.

Step 2 — Determine the required bump from the diff

Run git log <last-release-tag>..HEAD --oneline and read each affected crate's CHANGELOG.md ## Unreleased section. Cross-reference the changelog against the SemVer rule:

If the user-provided target version is smaller than what the diff requires, halt and report. If it is larger (e.g., user wants 0.5.0 but only patch-level changes are listed), warn and ask for confirmation — they may know about an additional breaking change not yet in the changelog.

Step 3 — Run the normal CI-equivalent checks

Run these from the repo root. All must pass:

# Format check (no fix — surface the diff so the user decides)
cargo fmt --all -- --check

# Clippy on 64-bit Word (warnings are errors)
cargo clippy --all-features --all-targets --workspace --exclude dashu-python -- -D warnings

# Clippy on 32-bit Word (the NTT module has 32-bit-specific paths)
RUSTFLAGS='--cfg force_bits="32"' cargo clippy --all-features --all-targets --workspace --exclude dashu-python -- -D warnings

# Check + tests with all features (matches CI)
cargo check --all-features --tests
cargo test --workspace --exclude dashu-python --all-features --no-fail-fast

# no_std path — ensures default code paths do not pull in std
cargo test --no-default-features --features rand --workspace --exclude dashu-python

Report any failure verbatim. Do not auto-fix unless the user asks — these checks gate the release, so the user must own the fix.

Step 4 — Verify CHANGELOG.md is updated for every affected crate

For each crate being published (and any crate whose version is bumped as a dependency side-effect):

1. Open <crate>/CHANGELOG.md.
2. Confirm ## Unreleased exists and is non-empty.
3. Confirm every notable commit since the last release of that crate is reflected. Use git log <last-tag-for-crate>..HEAD -- <crate>/ to find commits that touched the crate.
4. Confirm an MSRV change is mentioned in the changelog if and only if rust-version changed (see Step 6).

If a crate's ## Unreleased is empty or missing entries, halt with a list of uncovered commits.

Step 5 — Backward-compatibility verification

Use cargo-semver-checks to compare the working tree against the currently-published version on crates.io. Bump the version in <crate>/Cargo.toml first — the tool picks its crates.io baseline from the version declared there, so running it before the bump compares against the wrong version (often the same one):

# Install if missing
cargo install cargo-semver-checks --locked

# Run against the specific crate(s) being released
cargo semver-checks check-release --package <crate-name> --verbose

Interpret the output against the project's pre-1.0 SemVer rule:

• If target is a patch bump: zero semver violations are allowed. Any major or minor finding from semver-checks is a hard failure.
• If target is a minor bump (breaking for this project): major/minor findings are allowed but each must correspond to an entry under ### Remove or ### Change in the changelog. Unlisted breakage is a hard failure.

If cargo-semver-checks is unavailable (e.g., MSRV-incompatible), fall back to a manual public-API diff:

# Install if missing
cargo install cargo-public-api --locked

# Compare current against the published version
cargo public-api --package <crate-name> diff <published-version>

Review the diff manually using the same rules.