Skip to content

Commit 4a31d8e

Browse files
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 <[email protected]>
1 parent b3c8346 commit 4a31d8e

File tree

1 file changed

+12
-3
lines changed

1 file changed

+12
-3
lines changed

release-content/migration_guides_template.md

Lines changed: 12 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -17,10 +17,19 @@ Aim to communicate:
1717

1818
Keep it short and sweet:
1919

20-
- Use bullet points and make sure it's searchable.
20+
- What, then why, then how to migrate.
21+
- Some helpful standardized phrases:
22+
- `OldType` is now `NewType`. Replace all references and imports.
23+
- The `Struct::method()` method now requires an additional `magnitude: f32` argument.
24+
- `Enum` has a new variant, `Enum::NewVariant`, which must be handled during `match` statements.
25+
- The `Type::method` method has been removed. Use `Type::other_method` instead.
26+
- The `crate::old_module` module is now `crate::new_module`. Update your imports.
27+
- `function` now returns `Option<String>`, instead of `String`.
28+
- Make sure it's searchable by directly naming the types and methods involved.
29+
- Use backticks for types, methods and modules (e.g. `Vec<T>` or `core::mem::swap`).
30+
- Use bullet points to explain complex changes.
2131
- Avoid headings. If you must, use only level-two headings.
22-
- Use backticks for types (e.g. `Vec<T>`) in either the title or the body.
23-
- Diff codeblocks can also be useful for succinctly communicating changes.
32+
- Diff codeblocks can be useful for succinctly communicating changes.
2433

2534
```diff
2635
fn my_system(world: &mut World) {

0 commit comments

Comments
 (0)