Add migration guide to Garden docs

Signed-off-by: methylDragon <[email protected]>

garden/install.md

@@ -57,3 +57,10 @@ Platforms supported at **best-effort** include arm architectures, Windows and
 macOS. See
 [this ticket](https://github.com/gazebo-tooling/release-tools/issues/597)
 for the full status.
+
+## Migration Guide
+
+Gazebo Garden is the first major release that [uses the Gazebo brand instead of Ignition](https://community.gazebosim.org/t/a-new-era-for-gazebo/1356). So if you are upgrading from a prior release (e.g. Fortress), you will need to do some steps to migrate your packages.
+
+- [Migration Guide](migration)
+

garden/migration.md

@@ -0,0 +1,163 @@
+# Migration Guide
+
+Hi community!
+
+As you know, a couple months ago it was announced that [we’d be retiring the “Ignition” name in favor of “Gazebo”.](https://community.gazebosim.org/t/a-new-era-for-gazebo/1356) This migration guide will serve you help you execute the necessary changes, and luckily it won’t be as troublesome as the move from Gazebo Classic!
+
+# Overview
+
+## Changes
+
+So what’s happening in practice? In summary:
+
+- Whenever the name `Ignition` or `ign` is used, the Gazebo counterpart (`Gazebo` or `gz`) will be used instead, preserving case
+- `ign-gazebo` / `Ignition Gazebo` will become `gz-sim` / `Gazebo Sim`
+- The Ignition logo will also be replaced by the Gazebo logo.
+
+These changes will be made in:
+
+- Websites
+- GitHub organizations and repositories
+- Documentation
+- UIs
+- Namespaces, command line tools, shared libraries, directories, APIs, files
+
+This means that a bulk of the migration effort will involve intelligent find-and-replaces of filenames, directories, and source code.
+
+You may also look at the [tracking GitHub issue](https://github.com/gazebo-tooling/release-tools/issues/698) if you need to trace any changes made to support the migration in the core libraries.
+
+## Tick-tocks and Hard-tocks
+
+This section provides just an overview of the different changes made, for a more detailed listing of tick-tocks, see the `[MIGRATION.md](http://MIGRATION.md)` file in each of the individual core libraries’ repositories. Additionally the migration pointers in a later section of this migration guide should help you get your packages ready and working with Gazebo.
+
+Generally speaking, you should still be able to use either the Ignition counterpart or Gazebo counterpart for **most things** if you are using Garden, due to explicit tick-tocking logic written in the stack. Just note that using the Ignition counterpart will generally cause deprecation warnings to emit.
+
+### Tick-tocks
+
+Tick-tocks for the following are implemented, though not all of them will emit deprecation warnings. These tick-tocks are implemented either as aliases, or otherwise have some sort of redirection mechanism (e.g. symlinks, directory retargets, string replacements in source) to target the Gazebo counterpart instead.
+
+Also, in the source code, most of these tick-tocks will have an associated comment calling out that they are deprecated, or have a `GZ_DEPRECATED()` macro call.
+
+<details>
+<summary>Tick-tocks</summary>
+
+**Namespaces**
+
+- Python namespaces
+    - e.g. `ignition.math.XXX` → `gz.math.XXX`
+- C++ namespaces
+    - e.g. `ignition::gazebo::XXX` → `gz::sim::XXX`
+- Message namespaces
+    - e.g. `ignition.msgs.XXX` → `gz.msgs.XXX`
+
+**Source**
+
+- Class names, members, functions, and variables in public headers
+    - e.g. `IgnitionFormatter` → `GzFormatter`
+- Public headers
+    - e.g. `include/ignition` → `include/gz`
+- Plugins
+    - e.g. `ignition::gazebo::systems::LiftDrag` → `gz::sim::systems::LiftDrag`
+- Shared libraries
+    - e.g. `libignition-gazebo-buoyancy-engine-system.so` → `gz-sim-buoyancy-engine-system`
+- C++ Macros in public headers
+    - e.g. `IGN_PARTITION` → `GZ_PARTITION`
+
+**CMake and Packaging**
+
+- CMake macros/functions
+    - e.g. `ign_find_package()` → `gz_find_package()`
+- CMake macro/function arguments
+    - e.g. `NO_IGNITION_PREFIX` → `NO_PROJECT_PREFIX`
+- CMake variables*
+    - e.g. `IgnOGRE2_FOUND` → `GzOGRE2_FOUND`
+    - Not every CMake variable is tick-tocked, but most of the ones that are used in downstream libraries are
+- CMake packages found by `gz_find_package()`
+    - e.g. `gz_find_package(IgnCURL)` → `gz_find_package(GzCURL)`
+- Debian packages
+    - e.g. `libignition-cmake3-dev` → `libgz-cmake3-dev`
+
+**Misc.**
+
+- Environment variables (names and values)
+    - e.g. `IGN_GAZEBO_RESOURCE_PATH` → `GZ_SIM_RESOURCE_PATH`
+- Command line
+    - e.g. `ign` → `gz`, `ign gazebo` → `gz sim`
+- GUI QML
+    - e.g. `IgnSpinBox` → `GzSpinBox`
+- Topics* (typically in tests)
+    - e.g. `/ignition/XXX` → `/gz/XXX`
+    - **Note:** `/gazebo` is NOT migrated to `/sim`
+- GitHub organizations and repositories
+    - e.g. `ignitionrobotics` → `gazebosim` , `ign-cmake` → `gz-cmake`
+- GitHub actions and workflows
+    - e.g. `ignition-tooling` → `gazebo-tooling`
+- Websites
+    - e.g. `[ignitionrobotics.org](http://ignitionrobotics.org)` → `gazebosim.org`
+- SDF and launch tags
+    - e.g. `<ignition-gui>` → `<gz-gui>`
+
+</details>
+
+### Hard-tocks
+
+There are some exceptions that have been hard-tocked instead, meaning that you **MUST** use the Gazebo counterpart. Using the Ignition counterpart will likely cause compilation or something else to break (unless it’s just a documentation change.)
+
+<details>
+<summary>Hard-tocks</summary>
+
+**Namespaces**
+
+- Ruby namespaces
+    - e.g. `ignition/math` → `gz/math`
+
+**Source**
+
+- C++ Macros in private headers (typically something in a `detail/` directory)
+    - e.g. `DETAIL_IGNITION_UTILS_WARN_RESUME` → `DETAIL_GZ_UTILS_WARN_RESUME`
+- Class names, members, functions, and variables in private headers, or function-local scope
+    - e.g. `kIgnAuthDomain` → `kGzAuthDomain`
+
+**CMake and Packaging**
+
+- Most includeable CMake files in `gz-cmake`
+    - e.g. `IgnUtils.cmake` → `GzUtils.cmake`
+- Gazebo library CMake project names
+    - e.g. `ignition-utils2` → `gz-utils2`
+- Internally used CMake variables
+    - e.g. `IGN_TRANSPORT_VER` → `GZ_TRANSPORT_VER`
+
+**Misc.**
+
+- Gazebo launchfiles
+    - e.g. `sim.ign` → `sim.gzlaunch`
+- Config and log paths (PENDING)
+    - e.g. `~/.ignition/gui/log` → `~/.gz/gui/log`
+- Fuel URL (PENDING)
+    - e.g. https://fuel.ignitionrobotics.org
+- Fuel cache paths (ALSO PENDING)
+    - e.g. `~/.ignition/fuel` → `~/.gz/fuel`
+- Library names in documentation and comments
+    - e.g. Ignition Gazebo → Gazebo Sim
+
+**Additionally**
+
+- `gz-common` plugins are deprecated, use `gz-plugin` instead
+- `gz-common` `SuppressWarning` is deprecated, use `gz-utils` instead
+
+Also, anything that is internal to the core Gazebo libraries and not used in downstream libraries (e.g. header guards, private headers or source, tests, documentation) is hard-tocked.
+
+</details>
+
+## Untocks
+
+A very small selection of things have not been migrated, mostly for backwards compatibility reasons (e.g. supporting Fortress.)
+
+- Branch names for versions of Gazebo libraries targeting releases before Garden
+    - e.g. `ign-cmake1`
+- Some links
+    - e.g. [https://osrf-migration.github.io/ignition-gh-pages](https://osrf-migration.github.io/ignition-gh-pages)
+- Fuel user agent related
+    - e.g. `X-Ign-Resource-Version`, `IgnitionFuelTools`
+
+# Migrating