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 <NthTensor@users.noreply.github.com>
This commit is contained in:
Alice Cecile 2025-03-28 12:11:12 -04:00 committed by GitHub
parent b3c83465b3
commit 4a31d8e91a
No known key found for this signature in database
GPG Key ID: B5690EEEBB952194

View File

@ -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<String>`, 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<T>` 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<T>`) 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) {