Merge pull request #1187 from gerbigf/docs-trg-migration-guide

docs: [TRG] Initial Proposal for a documentation TRG "Migration Guide" (1.09)

Author: tom-rm-meyer-ISST

DEPENDENCIES

@@ -1361,4 +1361,4 @@ npm/npmjs/@webassemblyjs/wasm-opt/1.14.1, MIT, approved, clearlydefined
 npm/npmjs/@webassemblyjs/wasm-parser/1.14.1, MIT, approved, clearlydefined
 npm/npmjs/@webassemblyjs/wast-printer/1.14.1, MIT, approved, clearlydefined
 npm/npmjs/@xtuc/ieee754/1.2.0, BSD-3-Clause, approved, #123
-npm/npmjs/@xtuc/long/4.2.2, Apache-2.0, approved, clearlydefined
+npm/npmjs/@xtuc/long/4.2.2, Apache-2.0, approved, clearlydefined

docs/release/trg-1/trg-1-09.md

@@ -0,0 +1,38 @@
+---
+title: TRG 1.09 - Migration Guide
+sidebar_position: 1
+---
+
+:::caution
+Proposed release date: "mandatory after": tbd
+:::
+
+| Status     | Created      | Post-History                           |
+|------------|--------------|----------------------------------------|
+| Draft      | 12-March-2025 | Initial contribution                  |
+| Active      | 23-May-2025 | Committer Meeting Review                  |
+
+## Why
+
+IT operations managers and end-users of a component need a way to understand the impact of a new release on their work. This could be a required database migration, a change in an API call or system behavior.
+
+Those changes aren't obvious just based on a changelog ([TRG 1.03](https://eclipse-tractusx.github.io/docs/release/trg-1/trg-1-3)) that usually only list all PRs within a release.
+
+## Description
+
+A migration guide **must** contain all relevant information for IT operation managers of a component to migrate an existing component from the previous to the new version. It must be placed in a directory named `/docs/admin`.
+
+It **must** also contain all relevant changes for end-users, such as changed API calls, component behaviour, added/deprecated customer facing features etc.
+
+The migration guide shall _explain_ relevant changes to operators and users and not simply list them.
+
+## Best Practices
+
+- A migration guide should support IT operations management and guide the efforts for updating dependent tools and processes.
+- There should be a dedicated migration guide per release that contains relevant changes for IT operations managers or end users : E.g. From 1.1.x -> 1.2.x, 1.2.x -> 2.0.x etc.
+- A migration guide should only explain those changes that require an action by IT operations managers or end-users of a component. It should not be a duplication of the changelog.
+
+## Examples
+
+- [EDC migration guide](https://github.com/eclipse-tractusx/tractusx-edc/tree/main/docs/migration)
+- [Portal migration guide](https://github.com/eclipse-tractusx/portal-assets/blob/v2.3.0/docs/admin/Version%20Upgrade/portal-upgrade-details.md)