4a31d8e91a
# 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>
1.4 KiB
1.4 KiB
| title | pull_requests | |||
|---|---|---|---|---|
| Feature that broke |
|
Copy the contents of this file into a new file in ./migration-guides, update the metadata, and add migration guide content here.
Goals
Aim to communicate:
- What has changed since the last release?
- Why did we make this breaking change?
- How can users migrate their existing code?
Style Guide
Keep it short and sweet:
- What, then why, then how to migrate.
- Some helpful standardized phrases:
OldTypeis nowNewType. Replace all references and imports.- The
Struct::method()method now requires an additionalmagnitude: f32argument. Enumhas a new variant,Enum::NewVariant, which must be handled duringmatchstatements.- The
Type::methodmethod has been removed. UseType::other_methodinstead. - The
crate::old_modulemodule is nowcrate::new_module. Update your imports. functionnow returnsOption<String>, instead ofString.
- Make sure it's searchable by directly naming the types and methods involved.
- Use backticks for types, methods and modules (e.g.
Vec<T>orcore::mem::swap). - 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.
fn my_system(world: &mut World) {
+ world.new_method();
- world.old_method();
}