Overview

Versioning of Folio modules is well understood. However, with the introduction of Kong and Keycloak it’s important to establish a common understanding for how these should be versioned.

Approach

We’re familiar with the versions comprised of three components… Major.Minor.Patch. We should continue to use this here.

When releasing folio-keycloak or folio-kong, the major and minor components of the version should be borrowed from the corresponding keycloak or kong version being used. The patch version should start at 0 and incremented as needed.

For example:

• Let’s say we start with Keycloak 23.1.2, the first two components of the folio-keycloak release should be 23.1, and the patch version should be 0. 23.1.0

• We then make some adjustments/additions customization (e.g. we add a new keycloak theme). The version of keycloak being used has not changed, so we just bump the patch version. 23.1.0 → 23.1.1

• Later, we upgrade to Keyloak 25.0.3. Here we borrow the major and minor versions, resulting in a jump from 23.1.1 → 25.0.0.

• We then need to upgrade to Keycloak 25.0.4 which contains a high priority security fix… This is just a requires a patch version bump. 25.0.0 → 25.0.1

• Keycloak 25.1.0 is released with some feature we’d like to leverage. Again, we borrow the major and minor components. 25.0.1 → 25.1.0

Branching

Creating long lived release branches for each major+minor version probably makes sense here, as it will allow for easy backporting if needed.

For example: When we upgrade to Keycloak 25.0, we create a long-lived branch 25.0 and cut our releases off that branch. When we upgrade to Keycloak 25.1, we create a long-lived branch 25.1 and cut 25.1.x releases from there.