From 4a31d8e91a2ffad1af3a5c2b8376ecc0184f8e8d Mon Sep 17 00:00:00 2001 From: Alice Cecile Date: Fri, 28 Mar 2025 12:11:12 -0400 Subject: [PATCH] Use desired language in migration guide template (#18576) # Objective Both reading and writing migration guides is easier when the language is standardized. However, migration guide authors don't have clear guidelines for the tone and phrasing to use. ## Solution Communicate this information to authors by creating stub text with a clear and polite standard style. We could instead write a style guide, but turning style guides into a writing style is slower and much harder than simply filling in the blanks. While style guides are a good fit for more free-form writing, they don't work well for the very mechanical and dry migration guides. --------- Co-authored-by: Miles Silberling-Cook --- release-content/migration_guides_template.md | 15 ++++++++++++--- 1 file changed, 12 insertions(+), 3 deletions(-) diff --git a/release-content/migration_guides_template.md b/release-content/migration_guides_template.md index 5e02375c89..465679ed90 100644 --- a/release-content/migration_guides_template.md +++ b/release-content/migration_guides_template.md @@ -17,10 +17,19 @@ Aim to communicate: Keep it short and sweet: -- Use bullet points and make sure it's searchable. +- What, then why, then how to migrate. +- Some helpful standardized phrases: + - `OldType` is now `NewType`. Replace all references and imports. + - The `Struct::method()` method now requires an additional `magnitude: f32` argument. + - `Enum` has a new variant, `Enum::NewVariant`, which must be handled during `match` statements. + - The `Type::method` method has been removed. Use `Type::other_method` instead. + - The `crate::old_module` module is now `crate::new_module`. Update your imports. + - `function` now returns `Option`, instead of `String`. +- Make sure it's searchable by directly naming the types and methods involved. +- Use backticks for types, methods and modules (e.g. `Vec` or `core::mem::swap`). +- Use bullet points to explain complex changes. - Avoid headings. If you must, use only level-two headings. -- Use backticks for types (e.g. `Vec`) in either the title or the body. -- Diff codeblocks can also be useful for succinctly communicating changes. +- Diff codeblocks can be useful for succinctly communicating changes. ```diff fn my_system(world: &mut World) {