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 be 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. v23.1.0

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

• Later, we upgrade to Keycloak 25.0.3. Here we borrow the major and minor versions, resulting in a jump from v23.1.1 → v25.0.0.

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

• Keycloak 25.1.0 is released with some feature we’d like to leverage. Again, we borrow the major and minor components. v25.0.1 → v25.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 b25.0 and cut our v25.0.x releases off that branch. When we upgrade to Keycloak 25.1, we create a long-lived branch b25.1 and cut v25.1.x releases from there.