diff --git a/src/guidelines/checklist/README.md b/src/guidelines/checklist/README.md index 846042f..46a3889 100644 --- a/src/guidelines/checklist/README.md +++ b/src/guidelines/checklist/README.md @@ -56,6 +56,7 @@ - [ ] Prefer 'macros by example' over proc macros ([M-EXAMPLE-OVER-PROC]) - [ ] Macros don't lie about signatures ([M-MACROS-DONT-LIE]) - [ ] Macros assume main crate ([M-MACRO-MAIN-CRATE]) + - [ ] Pin supporting proc macro crates ([M-MACRO-VERSION-PIN]) - [ ] Third party items come from hidden `_private` module ([M-MACRO-HELPERS]) - [ ] Proc macros should have separate impl crate incl. tests ([M-PROC-IMPL]) - [ ] Proc macros don't produce implied or hidden items ([M-PROC-IMPLIED-ITEMS]) @@ -203,6 +204,7 @@ [M-EXAMPLE-OVER-PROC]: ../macros/#M-EXAMPLE-OVER-PROC [M-MACROS-DONT-LIE]: ../macros/#M-MACROS-DONT-LIE [M-MACRO-MAIN-CRATE]: ../macros/#M-MACRO-MAIN-CRATE +[M-MACRO-VERSION-PIN]: ../macros/#M-MACRO-VERSION-PIN [M-MACRO-HELPERS]: ../macros/#M-MACRO-HELPERS [M-PROC-IMPL]: ../macros/#M-PROC-IMPL [M-PROC-IMPLIED-ITEMS]: ../macros/#M-PROC-IMPLIED-ITEMS diff --git a/src/guidelines/macros/M-MACRO-VERSION-PIN.md b/src/guidelines/macros/M-MACRO-VERSION-PIN.md new file mode 100644 index 0000000..ba1ecd7 --- /dev/null +++ b/src/guidelines/macros/M-MACRO-VERSION-PIN.md @@ -0,0 +1,37 @@ + + +## Pin supporting proc macro crates (M-MACRO-VERSION-PIN) { #M-MACRO-VERSION-PIN } + +keep generated code compatible with its library + +A crate that re-exports macros from a companion proc macro crates must pin those dependencies +to its own exact version via `=x.y.z` and publish all related crates at the same time with the +same exact version. + +Without exact pins, a newer macro may generate code that relies on types or helpers added +in a newer library release. This can break compilation with an older library, even when +the additions were semver compatible. + +M-MACRO-VERSION-PIN does not apply to independently consumed macro libraries. + +Example: + +```toml +# my_crate/Cargo.toml +[package] +version = "1.2.3" + +[dependencies] +my_crate_macros = "=1.2.3" + +# my_crate_macros/Cargo.toml +[package] +version = "1.2.3" + +[dependencies] +my_crate_macros_impl = "=1.2.3" + +# my_crate_macros_impl/Cargo.toml +[package] +version = "1.2.3" +``` diff --git a/src/guidelines/macros/README.md b/src/guidelines/macros/README.md index 54c02cf..17f7804 100644 --- a/src/guidelines/macros/README.md +++ b/src/guidelines/macros/README.md @@ -6,6 +6,7 @@ {{#include M-EXAMPLE-OVER-PROC.md}} {{#include M-MACROS-DONT-LIE.md}} {{#include M-MACRO-MAIN-CRATE.md}} +{{#include M-MACRO-VERSION-PIN.md}} {{#include M-MACRO-HELPERS.md}} {{#include M-PROC-IMPL.md}} {{#include M-PROC-IMPLIED-ITEMS.md}}