Make some changes to the migration guide recommendations (#18794)

# Objective

- I've worked on the migration guide in the past, so I've written down
some of the conventions and styles I've used.

## Solution

Please read through the descriptions of each commit, which justify the
change! In summary:

- Remove headings from migration guide template by moving style guide to
`migration_guides.md`
- Use parentheses to signal method and function names (`my_func()`
instead of `my_func`)
- Change the guidelines on using bullet points so they're not used for
every single migration guide.
- Remove suggestion to use diff blocks, as they don't syntax-highlight
Rust code.

---------

Co-authored-by: Rob Parrett <[email protected]>
Co-authored-by: Miles Silberling-Cook <[email protected]>
Co-authored-by: Alice Cecile <[email protected]>

Author: 4 people

release-content/migration_guides.md

@@ -55,3 +55,48 @@ However, it's not always possible to use this attribute, and Bevy does not consi
 #[deprecated(since = "0.17.0", note = "This message will appear in the deprecation warning.")]
 struct MyStruct;
 ```
+
+## 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 when listing affected types / functions of a breaking change, or when the listing several complex steps for migrating. Avoid bullets for simple migrations, however.
+- Avoid headings. If you must, use only level-two (`##`) headings.
+- It's often useful to give a code example explaining what a migration may look like.
+
+  ```rust
+  // 0.15
+  fn my_system(world: &mut World) {
+      world.old_method();
+  }
+
+  // 0.16
+  fn my_system(world: &mut World) {
+      // Use `new_method()` instead.
+      world.new_method();
+  }
+  ```
+
+  Often you will want to give two examples of the same piece of code, one for the old version and one for the new. You can designate which is which using comments, such as `// 0.15` and `// 0.16`. Avoid code diffs if possible, as they do not syntax highlight Rust code.
+
+- Make sure to reference the currently published version of a crate when writing a migration guide.
+  See [docs.rs](https://docs.rs/) for a quick reference to the existing public API.
+- When moving items to a new module or crate, consider a simple table listing
+  the moved items and the before and after paths.
+  For example, "`Foo` has been moved from `bar::foo` to `baz`" could be written:
+  
+  **Relocations**
+  
+  |Item|0.15 Path|0.16 Path|
+  |-|-|-|
+  |`Foo`|`bar::foo`|`baz`|

release-content/migration_guides_template.md

@@ -5,47 +5,10 @@ pull_requests: [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:
+Remember, your aim is 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.
-  
-  ```diff
-   fn my_system(world: &mut World) {
-  +    world.new_method();
-  -    world.old_method();
-   }
-  ```
-  
-- Make sure to reference the currently published version of a crate when writing a migration guide.
-  See [docs.rs](https://docs.rs/) for a quick reference to the existing public API.
-- When moving items to a new module or crate, consider a simple table listing
-  the moved items and the before and after paths.
-  For example, _`Foo` has been moved from `bar::foo` to `baz`_ could be written:
-  
-  **Relocations**
-  
-  | Item                         | Old Path                       | New Path                       |
-  | ---------------------------- | ------------------------------ | ------------------------------ |
-  | `Foo`                        | `bar::foo`                     | `baz`                          |
+For more specifics about style and content, see the [instructions](./migration_guides.md).