Add Advice for Relocations to Migration Guide Template (#18654)

# Objective

Relocations are a fairly common form of migration, and a tabular format
can make reading an otherwise repetitive list much easier. This should
be included in the migration guide template.

## Solution

- Added a dot-point highlighting a tabular format for relocations, with
an explanation.
- Added a dot-point indicating migrations should be written WRT the
currently published version of a crate.
- Fixed some formatting in an adjacent dot-point.

## Testing

- CI
This commit is contained in:
Zachary Harrold 2025-04-02 04:18:59 +11:00 committed by GitHub
parent cbc023b3bb
commit 61f3b3e8f5
No known key found for this signature in database
GPG Key ID: B5690EEEBB952194

View File

@ -30,10 +30,22 @@ Keep it short and sweet:
- 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();
}
```
```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` |