TRG 1.09 - Migration Guide
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) 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.