From 61f3b3e8f59c352b586332af59bedf44d4e1b328 Mon Sep 17 00:00:00 2001 From: Zachary Harrold Date: Wed, 2 Apr 2025 04:18:59 +1100 Subject: [PATCH] Add Advice for Relocations to Migration Guide Template (#18654) # Objective Relocations are a fairly common form of migration, and a tabular format can make reading an otherwise repetitive list much easier. This should be included in the migration guide template. ## Solution - Added a dot-point highlighting a tabular format for relocations, with an explanation. - Added a dot-point indicating migrations should be written WRT the currently published version of a crate. - Fixed some formatting in an adjacent dot-point. ## Testing - CI --- release-content/migration_guides_template.md | 26 ++++++++++++++------ 1 file changed, 19 insertions(+), 7 deletions(-) diff --git a/release-content/migration_guides_template.md b/release-content/migration_guides_template.md index 465679ed90..ca1e367157 100644 --- a/release-content/migration_guides_template.md +++ b/release-content/migration_guides_template.md @@ -30,10 +30,22 @@ Keep it short and sweet: - Use bullet points to explain complex changes. - Avoid headings. If you must, use only level-two headings. - Diff codeblocks can be useful for succinctly communicating changes. - -```diff -fn my_system(world: &mut World) { -+ world.new_method(); -- world.old_method(); -} -``` + + ```diff + fn my_system(world: &mut World) { + + world.new_method(); + - world.old_method(); + } + ``` + +- Make sure to reference the currently published version of a crate when writing a migration guide. + See [docs.rs](https://docs.rs/) for a quick reference to the existing public API. +- When moving items to a new module or crate, consider a simple table listing + the moved items and the before and after paths. + For example, _`Foo` has been moved from `bar::foo` to `baz`_ could be written: + + **Relocations** + + | Item | Old Path | New Path | + | ---------------------------- | ------------------------------ | ------------------------------ | + | `Foo` | `bar::foo` | `baz` |