Merge pull request #1711 from DSD-DBS/t4c-update

docs: Improve TeamForCapella model migration docs

docs/docs/admin/teamforcapella/migration.md

@@ -3,21 +3,30 @@
  ~ SPDX-License-Identifier: Apache-2.0
  -->
 
-# How to Update a Capella Model to a Higher Version (in TeamForCapella)
+# How to Migrate a Capella Model to a Higher Version (in TeamForCapella)
 
 !!! warning
 
-    Please create backups (e.g., in a Git repository) before you start the update process.
     A downgrade of Capella models is not possible.
 
 1.  Open a new persistent session with the old Capella version.
+1.  Check that nobody is connected to the remote repository:
+    [See who is connected to a TeamForCapella repository](../../user/tools/capella/teamforcapella/connect/index.md)
+1.  Run a backup pipeline and verify that the latest changes are included in
+    the Git repository. If the Git repository is already up-to-date, there will
+    be no additional commit. In this case, you should check the status of the
+    pipeline run.
 1.  Import the model from the TeamForCapella server via the Import wizard from
     TeamForCapella into your local workspace:
     [Import a model from TeamForCapella](../../user/tools/capella/teamforcapella/import/index.md)
+1.  If you're still connected to the old Capella repository (`*.team` project
+    in the workspace), delete the `*.team` project.
 1.  Terminate the session.
-1.  Remove existing backups from TeamForCapella:
+1.  Remove existing TeamForCapella to Git backup pipelines in the Collaboration
+    Manager and note down if the commit history is included:
     [Remove a (nightly) backup](../../user/projects/models/backups/remove.md)
-1.  Add a new repository in the TeamForCapella settings:
+1.  Add a new repository in the TeamForCapella server with the new Capella
+    version via the Capella Collaboration Manager:
     [Add a new TeamForCapella repository](./repository-management/index.md#add-a-new-teamforcapella-repository)
 1.  Unlink the old TeamForCapella repository (old Capella version) from your
     model:
@@ -36,8 +45,23 @@
        on the old TeamForCapella server.
        ![Disable backup option](../../user/tools/capella/migration/backup-migration.png)
 
-1.  Export the model to the new TeamForCapella server via the Export wizzard
+1.  Export the model to the new TeamForCapella server via the Export wizard
     from TeamForCapella:
     [Export a model to TeamForCapella](../../user/tools/capella/teamforcapella/export/index.md)
-1.  Recreate the backup pipeline:
-    [Set up a TeamForCapella backup](../../user/projects/models/backups/setup.md)
+1.  If you have CI/CD pipelines in the linked Git repositories which depend on
+    a specific Capella version, make sure to update them. For our pipelines it
+    might be necessary to update the `CAPELLA_VERSION` environment variable.
+1.  Recreate the backup pipeline(s) for the new TeamForCapella server version:
+    [Set up a TeamForCapella backup](../../user/projects/models/backups/setup.md).
+    Start a pipeline run and verify that the changes are included in the Git
+    repository. Verify also that the CI/CD pipelines in the linked Git
+    repository are still working (if applicable).
+1.  Use the [capella-diff-tools](https://github.com/DSD-DBS/capella-diff-tools)
+    and compare the commit after the migration with the commit before the
+    migration. Verify that the changes are correct.
+1.  Communicate to all users that the model has been migrated to a new version.
+    Users have to reimport the repositories in their personal workspace. Share
+    the following documentation page with all users:
+    [Steps after a Model Migration](../../user/tools/capella/teamforcapella/migration/index.md)
+1.  At a later point, when the new repository is stable on the new server:
+    [Remove the old TeamForCapella repository from the old server](./repository-management/index.md#remove-a-teamforcapella-repository)

docs/docs/user/tools/capella/teamforcapella/export/index.md

@@ -22,7 +22,7 @@
    button and enter your [session token](../connect/index.md). Click on `Next`.
    ![Select repository for export](./export-repository-selection.png)
 1. Select the overwrite strategy. If the project doesn't exist on the server
-   yet, choose `Replace`. Otherwise, select `Merge`.
+   yet, choose `Replace`. Otherwise, select `Merge`. <br>
    ![Overwrite strategy](./select-overwrite-strategy.png)
 1. In the next step, you have to select images to export.
 1. Finish the export with `Finish`.

docs/docs/user/tools/capella/teamforcapella/migration/index.md

@@ -0,0 +1,21 @@
+<!--
+ ~ SPDX-FileCopyrightText: Copyright DB InfraGO AG and contributors
+ ~ SPDX-License-Identifier: Apache-2.0
+ -->
+
+You probably got this page because one of your models has been migrated to a
+newer version of Capella. After the migration, there are some manual steps that
+you need to follow in order to continue working with the model:
+
+1. Request a session with the new Capella version. Identify the migrated
+   projects and remove the old `.team` projects from your workspace:
+
+    ![Remove old .team projects](./remove-project-from-workspace.png){:style="width:400px"}
+
+    A popup will appear asking you to confirm the deletion. Tick the box to
+    delete the project from the disk and confirm:
+
+    ![Confirm deletion](./project-deletion-popup.png){:style="width:400px"}
+
+1. Connect to the new TeamForCapella repository:
+   [Connect to a TeamForCapella repository](../connect/index.md)

docs/docs/user/tools/capella/teamforcapella/migration/project-deletion-popup.png.license

@@ -0,0 +1,2 @@
+SPDX-FileCopyrightText: Copyright DB InfraGO AG and contributors
+SPDX-License-Identifier: Apache-2.0

docs/docs/user/tools/capella/teamforcapella/migration/remove-project-from-workspace.png.license

@@ -0,0 +1,2 @@
+SPDX-FileCopyrightText: Copyright DB InfraGO AG and contributors
+SPDX-License-Identifier: Apache-2.0

docs/mkdocs.yml

@@ -61,6 +61,7 @@ nav:
               - Export a Model to TeamForCapella: user/tools/capella/teamforcapella/export/index.md
               - TeamForCapella commits and commit messages: user/tools/capella/teamforcapella/commit-messages/index.md
               - See Other Connected Users: user/tools/capella/teamforcapella/connected-users/index.md
+              - Steps after a Model Migration: user/tools/capella/teamforcapella/migration/index.md
           - Git:
               - Working with Git: user/tools/capella/git/index.md
           - Troubleshooting: user/tools/capella/troubleshooting/index.md