feat: introduce M-MACRO-VERSION-PIN - #65
Conversation
Removed unnecessary comments and code related to 'my_macro!' implementation.
Added a new section to explain the guideline for pinning supporting proc macro crates.
Clarify version pinning guidelines for proc macro crates and emphasize the importance of matching version numbers across main and supporting crates.
Clarify the versioning guidelines for macro dependencies.
…st entry
Two defects in the new guideline, both found by building the book rather than
by reading the source.
**The example's file headers are hidden in the rendered page.** The block is
Cargo.toml content fenced as rust,ignore. mdBook treats a leading `#` in a
*Rust* block as a hidden "boring" line, so all three `# my_crate/Cargo.toml`,
`# my_crate_macros/Cargo.toml` and `# my_crate_macros_impl/Cargo.toml` comments
are stripped of their `#`, wrapped in `<span class="boring">`, and hidden by
default (`book.js` adds `hide-boring`; `general.css` sets
`.hide-boring .boring { display: none }`).
Those comments are the only thing telling the reader which of the three
manifests each `[package]` belongs to, and this guideline is *entirely* about
three different crates' manifests. As published the reader sees three
undifferentiated `[package]`/`[dependencies]` pairs. Verified by building both
ways from the same tree:
rust,ignore -> <code class="language-rust ignore"><span class="boring">my_crate/Cargo.toml
toml -> <code class="language-toml"># my_crate/Cargo.toml
Retagging as toml also gives correct highlighting and removes a Rust-doctest
fence around content that is not Rust. `rust,ignore` is right for the Rust
snippets elsewhere in this book; it is wrong for a manifest. The five existing
manifest examples (M-TARGET-CPU, M-MIMALLOC-APPS, M-HOTPATH, M-PANIC-IS-STOP,
M-CRATES-IN-WORKSPACE) already use a toml fence, so this restores the
convention rather than inventing one.
**The guideline is missing from the checklist.** Every other `M-` guideline
appears in `src/guidelines/checklist/README.md` with a link definition; without
its row the guideline is unreachable from the page teams actually review
against, which is the cost that matters for a rule nobody can look up.
Verified: `mdbook build` and `mdbook test` both exit 0; the rebuilt
`book/guidelines/macros/index.html` contains `language-toml` and zero `boring`
spans; `book/guidelines/checklist/index.html` renders the new row linking to
`../macros/#M-MACRO-VERSION-PIN`, and that `id` exists on the target page;
`markdownlint-cli2` reports 0 errors on both changed files with the repo's
`.markdownlint.json`.
Generated artifacts touched by the preprocess scripts (`src/agents/all.txt`,
the `BUILD_DATE` placeholder in `src/guidelines/README.md`) were reverted
rather than committed -- CI regenerates them on every run, and the base PR
does not carry them.
Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
|
Pushed The example's file headers are hidden in the rendered pageThe block is Those comments are the only thing telling the reader which of the three manifests each Built both ways from the same tree to confirm rather than assert: Retagging as The guideline was missing from the checklistEvery other Verification
Generated artifacts the preprocess scripts touch — Happy to drop either change if you would rather keep the PR to the guideline text alone. |
Clarify guidelines for pinning dependencies of proc macro crates to ensure compatibility.
Clarify the requirement to pin macro dependencies to exact versions and release them together.
Clarified the impact of not using exact version pins for macros, emphasizing potential compilation issues with older libraries.
Clarified guidelines for pinning proc macro crate versions and publishing.
1 participant
No description provided.