Upgrading with Git

Last updated 15 days ago

Learn how to upgrade your CoreMedia workspace with Git.

What you'll learn

Find a version to upgrade to
Perform the upgrade

Prerequisites

A CoreMedia workspace forked from the CoreMedia Blueprint workspace
A Github account

Time matters

Reading time: 10 minutes

Should I read this?

This guide is for Developers.

Table of Contents

Prerequisites
Upgrade Steps

The recommended way to upgrade your CoreMedia workspace is to use Git. This way, you can easily track changes and merge them with your customizations.

The following steps describe how to upgrade your workspace with Git:

Prerequisites

You have started your CoreMedia project by forking from the CoreMedia Blueprint GitHub repository.
You have started your main development branch from a certain CMCC version, which is indicated by a corresponding tag on a commit in the Git repository, for example, cmcc-10-2107.3.
```
git checkout -b main cmcc-10-2107.3
```

Upgrade Steps

When you have set up your CoreMedia project as described in the prerequisites, before starting an update, you must pull in the latest releases from CoreMedia. If you have not done so already, you must once add a "remote" for the CoreMedia Blueprint repository:
```
git remote add upstream https://github.com/coremedia-contributions/coremedia-blueprints-workspace.git
```
Then, you can keep your fork up to date using the following command:
```
git fetch upstream
```
This fetches all new commits, which correspond to Blueprint releases.

You can now upgrade to any version (a tagged commit) that is a successor of the commit you started from. To check whether this is the case, use the following command:

git merge-base --is-ancestor <start-version-commit> <target-version-commit>; echo $?

This outputs "0" when upgrading is possible and "1" when it is not. For example, when you have started on CMCC 10 2107.8 and want to upgrade to CMCC 11 2210.2, you can use the following command:

git merge-base --is-ancestor cmcc-10-2107.8 cmcc-11-2210.2; echo $?

This should result in "1" (update not possible). An example that prints "0" (update possible) would be to use the target version CMCC 11 2310.2 (tag cmcc-11-2310.2).

One reason, that an upgrade to a specific version is not recommended is, that this version was earlier end-of-life as the version you are currently on. Moving to such a version would be a downgrade for some bugfixes, which would lead to regressions. Another reason is that there are some missing connections in CoreMedia’s Blueprint version history, which unfortunately cannot be fixed, because Git history must not be rewritten.

In the branching version history of CoreMedia version commits, there might be more than one path from the start version to the target version. Since automatic conversion commits for the TypeScript conversion were introduced only for later 2107 AMP releases (2107.8 and up), to take advantage of these, find a path that includes a …-ts tag. See the diagram below for an overview of all version commits and paths.
When you have found a suitable version to upgrade to, you can merge your main branch with this version’s commit.
```
git merge <target-version>
```
There may be conflicts, but if you follow this documentation, these should be limited to lines of code that have actually been changed by you and CoreMedia in parallel. If the conflict resolution is not obvious, there should be a release note explaining the change and giving instructions on how to adapt your code. If there are too many conflicts, consider upgrading to an earlier version first (see next bullet item). In case of doubt, contact CoreMedia support.

You can "stop by" on any intermediate version as a checkpoint and try to get everything to work, or you can skip any intermediate version, with the following exception:

When your update path includes an automatic conversion commit, shown as a square in the upgrade path diagram, and indicated by a …-ts or …-converted commit tag, you must upgrade to its direct ancestor commit first. Then, apply the corresponding automatic conversion (TypeScript/npm workspace converter tool, linter, etc., see documentation for the corresponding tools) to your workspace. Next, ignore-merge the automatic conversion commit: git merge -s ours <automatic-conversion-commit>

The intermediate stop at automatic conversion commits leads to better merge results. Git can then perform a three-way-merge with a common merge base instead of a baseless merge. For example, for the type script conversion, the merge base must also be in TypeScript like the two commits being merged. If the merge base were in ActionScript and the commits to merge were already in TypeScript, every line would be different, essentially resulting in a baseless merge. Therefore, the ignore-merge merge converts the merge-base to TypeScript.

Then, you can continue as before, merging or skipping version commits on your upgrade path as you like, unless you encounter another automatic conversion commit.

Is this page useful?