docs: [TRG] Initial Proposal for a documentation TRG "Migration Guide" (1.09) #1187
+38
−1
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,37 @@ | ||
| --- | ||
| 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 | | ||
|
|
||
| ## 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 | ||
|
There was a problem hiding this comment. I really hate the fact, that TRGs are currently not very consistent in their structure. 20 TRGs use I suggest switching to There was a problem hiding this comment. @ClosedSourcerer Examples and Best Practices are two different things for me. I chose not to provide an example, because this always depends on the application... We could however link to "good examples" that already do that, such as the portal or the EDC. I'd still like to keep the best practices... would you suggest to add them to the "description"? |
||
|
|
||
| - 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) | ||
Oops, something went wrong.
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
I suggest to change the date to May, 16 2025 and the status to active: we'd merge it then during the committer meeting of May, 16 2025
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Done.