Release evidence

mdwright release candidates are judged by local evidence, not by a claim of full cmark-gfm parser equivalence. The release claim is:

mdwright is a round-trip-safe Markdown formatter and linter with classified GFM/parser divergences and an opt-in mdformat-compatible style profile.

The release bundle lives under target/mdwright/release/. It is a local artifact; do not commit it.

Aggregate the evidence

Run:

cargo xtask release-evidence --output target/mdwright/release

The command writes:

  • target/mdwright/release/release-evidence.json
  • target/mdwright/release/release-evidence.md

The command does not rerun every expensive gate. It records git state and tool versions, reads existing machine reports, points at manual evidence notes, and lists blockers when evidence is missing. This keeps the command narrow: it summarizes release evidence instead of duplicating parser audit, mdformat parity, production soak, fuzzing, packaging, or benchmarks.

Refresh machine reports

Run these before aggregating a release candidate:

cargo check --workspace --all-targets
cargo nextest run --workspace --no-fail-fast
cargo clippy --workspace --all-targets -- -D warnings
cargo fmt --check
cargo doc --workspace --no-deps
mdbook build docs/
cargo xtask doc-rules --check
cargo xtask doc-cli --check
cargo xtask doc-config --check
python3 scripts/check_package_docsrs.py --allow-dirty
actionlint .github/workflows/*.yml

cargo xtask parser-audit --case-set all --ensure-tools --include-comrak
cargo xtask mdformat-parity \
  --corpus-root docs \
  --corpus-name mdwright-docs \
  --mdwright-config .mdwright.toml \
  --mdformat-config xtask/fixtures/mdformat-parity/mdformat.toml
cargo xtask production-soak \
  --corpus-root <external-corpus-path> \
  --output target/mdwright/production-soak

<external-corpus-path> is a directory of Markdown files used as the production-soak input; set it to the path of the external corpus you run releases against (or to MDWRIGHT_CORPUS_ROOT if you have one configured). Record the path in the release notes.

Record the fast-check result in target/mdwright/release/fast-checks.md. The aggregator treats that file as the manual proof that the local workspace gate was refreshed.

Refresh packaging evidence

The detailed crates.io release checklist lives at Crates.io release. Before tagging, run the release workflow manually with dry_run: true.

Package every publishable crate:

cargo package --workspace --exclude xtask --exclude mdwright-extra-example --allow-dirty --no-verify

Install the command package into an isolated root:

tmp="$(mktemp -d)"
CARGO_HOME="$tmp/cargo-home" \
CARGO_TARGET_DIR="$tmp/target" \
cargo install --path crates/mdwright --locked --root "$tmp/install"
"$tmp/install/bin/mdwright" --help
"$tmp/install/bin/mdwright" explain bare-url
"$tmp/install/bin/mdwright" check docs/src/introduction.md
"$tmp/install/bin/mdwright" fmt-check docs/src/introduction.md
"$tmp/install/bin/mdwright" render docs/src/introduction.md >/tmp/mdwright-render.html
"$tmp/install/bin/mdwright" lsp --help

Record the dry-run result in target/mdwright/package-dry-run/report.json. The report can be generated by hand; the aggregator only requires stable JSON with enough fields for a human to inspect alongside the Markdown report.

Refresh fuzz and benchmark evidence

Replay the fuzz corpora:

cargo +nightly fuzz run fuzz_parse_format -- -runs=0
cargo +nightly fuzz run fuzz_idempotence -- -runs=0
cargo +nightly fuzz run fuzz_structured_idempotence -- -runs=0
cargo +nightly fuzz run fuzz_lint -- -runs=0
cargo +nightly fuzz run fuzz_verbatim_identity -- -runs=0
cargo +nightly fuzz run fuzz_latex_render -- -runs=0
cargo +nightly fuzz run fuzz_latex_translate -- -runs=0
cargo +nightly fuzz run fuzz_markdown_math_translate -- -runs=0
cargo +nightly fuzz run fuzz_unicode_latex_roundtrip -- -runs=0

Write the replay result to target/mdwright/release/fuzz-replay.md.

Run sustained fuzz rounds with the helper script. The standard release target is three clean 10-minute rounds for every fuzz target:

scripts/fuzz-round.sh 600 3

The script writes target/mdwright/release/fuzz-sustained.md and per-target logs under target/mdwright/release/fuzz-sustained/logs/.

Run the Criterion comparison and write the result to target/mdwright/release/benchmarks.md:

cargo bench -p mdwright --bench format_bench --bench lint_bench -- --baseline pre-parser-boundary

Re-capture on the same hardware before declaring a regression.

Interpret the report

release-evidence.md is ready for review when:

  • the worktree is clean;
  • every required report is present;
  • manual fuzz, benchmark, and fast-check notes are present;
  • parser audit has no unclassified differences, mitigation rows, or uncontained panics;
  • mdformat parity has no unclassified differences, semantic drift, parse errors, idempotence failures, or open bugs;
  • production soak has no parse errors, validation errors, idempotence failures, or fmt-check disagreements;
  • packaging and isolated install dry runs passed.

Accepted divergences are documented in: