feat: introduce M-MACRO-VERSION-PIN

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

src/guidelines/macros/M-MACRO-VERSION-PIN.md

@@ -0,0 +1,37 @@
+<!-- Copyright (c) Microsoft Corporation. Licensed under the MIT license. -->
+
+## Pin supporting proc macro crates (M-MACRO-VERSION-PIN) { #M-MACRO-VERSION-PIN }
+
+<why>keep generated code compatible with its library</why>
+
+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"
+```

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}}