Creating a Release Branch

This page describes the release branch creation process for FOLIO Eureka applications — what it means, how it is initiated, and what happens during the automated preparation.

Overview

A release branch represents a stable, version-controlled line of an application for a specific FOLIO platform release (e.g., Sunflower, Tulip). Once created, the release branch receives only controlled module version updates through pull requests, in contrast to the pre-release branch where updates are committed directly.

Release branches follow the naming convention R1-2025, R2-2025, etc., corresponding to the platform release cycle.

Two Modes of Release Branch Creation

Release branches can be created in two ways, depending on the scope.

Centralized (Platform-Wide)

The platform repository maintainer triggers release-preparation-orchestrator.yml in platform-lsp. This orchestrator processes all application repositories included in the platform in parallel:

1. Extracts the application list from the previous release's platform-descriptor.json

2. Dispatches the release-preparation.yml workflow in each application repository concurrently

3. After all applications are processed, updates the platform template (platform.template.json) with ^VERSION constraints

4. Creates the release branch in platform-lsp itself

5. Adds the new branch configuration to platform-lsp's update-config.yml

This is the standard mode used for regular release cycles. For step-by-step execution instructions, see Running Release Preparation Workflows.

Single-Application

An application maintainer or the platform repository maintainer triggers release-preparation.yml directly in a specific application repository. This mode is used when:

• A new application is being added to a release mid-cycle

• A release branch needs to be re-created after an issue

• An application was not included in the platform-wide preparation and needs its own release branch

For step-by-step execution instructions, see Running Release Preparation Workflows.

What the Automation Does

When the release preparation workflow executes for an application repository, the following steps occur in sequence:

1. Determines the source branch — the previous release branch (e.g., R1-2025) serves as the base. If the previous release branch does not exist in the repository and use_snapshot_fallback is enabled, the default pre-release branch is used instead

2. Increments the application version in pom.xml — typically a major version bump (e.g., 1.0.0 → 2.0.0). See Version Increment Logic below for details on how the version is determined

3. Updates application.template.json:

   • All module versions are set to ^VERSION placeholders — these must be replaced manually by application maintainers with valid semver constraints before the update scheduler can process the branch

   • The preRelease field is set to "false" for all modules and dependencies

   • Dependency versions are updated with version constraints matching the expected release versions

4. Removes application.lock.json — the state file is deleted because it will be regenerated by the update scheduler once the branch exists

5. Adds the new branch configuration to update-config.yml on the default branch — the entry includes enabled: true, need_pr: true, preRelease: "false", and ruleset.enabled: true

6. Creates the release branch with all changes committed

7. Triggers branch ruleset automation — the branch-ruleset-automation workflow applies required CI checks and merge queue configuration for the new branch

8. Sends Slack notification announcing the new release branch

After the Branch Is Created

Once the release branch exists, application maintainers should verify the following:

• Module composition — review the module list in application.template.json on the release branch to confirm no modules were accidentally included or excluded

• Replace ^VERSION placeholders — all module versions on the new branch are initially set to ^VERSION. This is a placeholder, not a valid version constraint. Application maintainers must replace each ^VERSION with a valid semver constraint (e.g., ^2.0.0, ~2.1.0, >=2.0.0) before the update scheduler can process the branch. The scheduler skips applications with unresolved ^VERSION placeholders

• Application dependencies — confirm that dependency versions reference the correct release versions of other applications (e.g., app-licenses ^2.0.0)

• PR reviewers — ensure the appropriate team is listed in pr_reviewers in .github/update-config.yml so automated PRs are routed correctly

• First automated PR — once all ^VERSION placeholders have been replaced with valid semver constraints and pushed to the release branch, the update scheduler creates the first pull request within 20 minutes. This PR resolves the version constraints to specific module versions and establishes the initial release baseline. Review and approve this PR promptly

For details on how to manage the application on the release branch after creation, see Releasing Applications on a Release Branch.

Version Increment Logic

The automation determines the new application version based on the source branch and configuration:

The version is stored in pom.xml and does not use a -SNAPSHOT suffix on release branches. During subsequent PR-based updates on the release branch, the version receives a patch increment on the first update (e.g., 2.0.0 → 2.0.1).

What Not to Do

• Do not create release branches manually — always use the release-preparation workflow, either through the platform orchestrator or directly in the application repository

• Do not edit application.lock.json on the release branch — it is managed entirely by the CI system

• Do not disable the scheduler on the release branch without coordinating with the CI infrastructure team

• Do not modify workflow files (.github/workflows/) — they are centrally managed boilerplate

Related Pages

• Understanding Application Repository Files — Workflow Files — detailed reference for both workflows

• Releasing Applications on a Release Branch — managing the application after the release branch is created

• Managing Release Branch Updates — PR flow, merge queue, and troubleshooting