forestia/bevy
2
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
4a31d8e91a
bevy/release-content/migration_guides_template.md
Alice Cecile 4a31d8e91a
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>
2025-03-28 16:11:12 +00:00

1.4 KiB
Raw Blame History

title pull_requests
Feature that broke
14791
15458
15269

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:
    • 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.
  • Diff codeblocks can be useful for succinctly communicating changes.
fn my_system(world: &mut World) {
+ world.new_method();
- world.old_method();
}