Learn Rust with mrrc: a tutorial series for Python programmers

[dchud]

A tutorial series teaching Rust to Python programmers using mrrc itself as the guide material, living as a section of the mkdocs site. Audience: pymarc-familiar Python developers (the maintainer first, then friends). Each chapter opens in Python with the pymarc-shaped behavior the reader knows, then descends into the Rust that implements it, and anchors concepts to real merged PRs so every idea carries a measured or reviewable "why".

Proposed arc

Cut child beads per chapter when writing starts.

1. First principles — why Rust for this library: types, ownership, the compiler as collaborator; strategic trade-offs vs Python.
2. Ownership and borrowing through the parse buffer: the per-record copy chain and its removal (PRs Share the parse buffer by refcount instead of copying every record #292, Parse from owned bytes end-to-end; delete the per-record copy chain #294) as the narrative — ownership as a performance tool.
3. Enums, pattern matching, and errors: the 17-variant MarcError, the metadata() single-match table (PR Consolidate per-variant MarcError accessors behind a single metadata() table #317), non_exhaustive and API evolution (PR Mark MarcError and the grower enums non_exhaustive #318). Folds in the previously deferred ?/unwrap/expect exercise.
4. Traits and generics: the Iso2709Builder skeleton, monomorphization, and the salvage consolidation (PR Consolidate truncated-record salvage into the ISO 2709 skeleton #323) as "make the abstraction the single source of truth".
5. Project workflows: cargo, workspaces and manifest inheritance (PR Single-source the version and shared manifest fields via workspace inheritance #304), feature gates (PR Gate the BIBFRAME/RDF stack behind a default-on cargo feature #307), clippy/rustfmt, debugging.
6. Testing the Rust way: unit/integration/doc tests, property tests and roundtrip strategies (PR Add generative roundtrip properties for authority and holdings writers #306), fuzzing (PR Add fuzz targets for authority, holdings, BIBFRAME, and lenient-mode parsing #315), the error-code reconciliation harness.
7. Performance: criterion + CodSpeed, benchmark discipline (PRs Remove dead manual-profiling bench harnesses #309, Add criterion benches for uncovered serialization formats and the single-thread parser-pool path #312), the release-profile story (PR Tune the release profile: fat LTO, codegen-units=1, strip debuginfo #291), reading instruction-count vs wall-clock results.
8. CI for a Rust library: the workflow topology and what each gate catches, drawn from the hardening series (PRs Run a wheel build/test smoke job on Dependabot PRs #295-CI consistency: release env parity, cache unification, per-test retries, type-check gate, timeouts #311).
9. Capstone — wrapping for Python with PyO3/maturin: the GIL 3-phase model, the wrapper layer architecture, type stubs, and wheels.

Appendix: the human-agent collaboration workflow

An appendix (or sidebar chapter) on the human-agent collaboration workflow used to build mrrc — the bead lifecycle (create/ready/in_progress/close-after-verified-merge) and elevation to GitHub issues; CLAUDE.md and AGENTS.md as the working contract (check.sh gate, four-layer feature checklist, session-completion landing); decomposing review findings into epics and zero-file-overlap parallel agent tracks; the coordinator merge protocol (stacked PRs, post-squash rebases, milestone hygiene); and an honest what-went-wrong section with real artifacts:

• the v0.8 release itself, which shipped a documented 17-variant error-code taxonomy (E001–E404) without wiring many of the codes to the code paths that should raise them — found by the post-release audit epic bd-0x73, remediated across the 0.8.1 cycle (PRs Wire io_error/recovery_cap/writer triggers + fix E404 writer wiring #193, test(coverage): per-trigger manifest cases for E404 + restore E002/E005 changelog #198, Per-trigger error-coverage manifest expansion + harness extensions #212, Per-record-type MARC 21 leader validation at strict_marc #220, Wire E106 authority field-too-short coverage with a data-field fixture #223, Implement Clone for MarcError, wire lenient/recovery E005 and E106 cases #224 among others), and now guarded by the per-trigger error-coverage manifest (tests/error_coverage.toml) and the error-code reconciliation gate in check.sh and CI (Add error-code reconciliation guard and pymarc parity test #231, Backfill format-parser fuzz targets and guard error-code drift #255); the lesson is that documentation claims need an executable reconciliation against behavior, not review-time spot checks
• the beads JSONL auto-import revert
• the premature-merge bead reopen
• the CHANGELOG duplicate-subsection conflict
• the semver gate on an intentional removal
• the hung CI runner

Audience overlaps but differs from the Rust chapters; keep it self-contained so it can graduate to its own doc if it grows.

Format

Co-written — the maintainer attempts each chapter's exercise first and the prose gets shaped by what actually tripped them up. Code snippets should become compile-checked where practical (bd-4ap2 is the enabling work). Keep out of the library's reference docs nav tier; this is a learning track.

Bead: bd-kxjo