From 895a9931a6632f14f34ce91dc8624fd555babe4f Mon Sep 17 00:00:00 2001
From: nscuro <nscuro@protonmail.com>
Date: Thu, 11 Jun 2026 00:41:57 +0200
Subject: [PATCH] Document patch release procedure

While doing these steps it dawned on me they should be documented for project longevity.

Signed-off-by: nscuro <nscuro@protonmail.com>
---
 DEVELOPING.md |  4 ++++
 RELEASING.md  | 62 ++++++++++++++++++++++++++++++++++++++++++++++++++-
 2 files changed, 65 insertions(+), 1 deletion(-)

diff --git a/DEVELOPING.md b/DEVELOPING.md
index 0f30e38bcd..6871f647fb 100644
--- a/DEVELOPING.md
+++ b/DEVELOPING.md
@@ -207,6 +207,10 @@ For repeatable migrations, edit the relevant `R__*.sql` file directly, no new fi
 > Flyway rejects checksum mismatches on existing deployments.
 > Add a new migration instead.
 
+> [!NOTE]
+> Migrations run with `outOfOrder=true` so they can be backported to patch branches
+> without blocking the next minor upgrade. See [`RELEASING.md`](./RELEASING.md#4-flyway-migrations).
+
 ## Build Cache
 
 We use Maven [build caching](https://maven.apache.org/extensions/maven-build-cache-extension/) to speed
diff --git a/RELEASING.md b/RELEASING.md
index 197ce5b44e..518ffe2e41 100644
--- a/RELEASING.md
+++ b/RELEASING.md
@@ -2,6 +2,65 @@
 
 This document describes the process of releasing a new version of Dependency-Track.
 
+## Patch Releases
+
+Patch releases (e.g. `5.0.1`) ship bugfixes and security fixes off a release branch.
+No new features, no breaking changes.
+
+> [!IMPORTANT]
+> Backport, don't forward-port. Merge the fix on `main` first, then cherry-pick onto the patch branch.
+> Direct commits on the patch branch are fine for fixes that no longer apply to `main`.
+
+### 1. Cut or check out the patch branch
+
+First patch in a series, branched from the GA tag:
+
+```shell
+git checkout -b 5.0.x 5.0.0
+git push -u origin 5.0.x
+```
+
+Subsequent patches:
+
+```shell
+git checkout 5.0.x
+git pull
+```
+
+### 2. Bump the Maven version (first patch only)
+
+Run from the repository root:
+
+```shell
+mvn versions:set -DnewVersion=5.0.1-SNAPSHOT -DgenerateBackupPoms=false
+```
+
+Commit (signed off, i.e. with `--signoff`). Follow-up patches are bumped automatically by the [Release CI].
+
+### 3. Cherry-pick backports
+
+Open one PR per backport against the patch branch, using the branch name `backport-pr-<original-PR-number>`:
+
+```shell
+git checkout -b backport-pr-1234 5.0.x
+git cherry-pick -s <sha>
+```
+
+Resolve any conflicts, then `git cherry-pick --continue`.
+
+### 4. Flyway migrations
+
+When backporting a migration, cherry-pick the file as-is. **Do not rename or re-timestamp it**.
+Out-of-order execution is enabled, so users upgrading from a patch release to the next minor
+will still get any older mainline migrations applied. See [Flyway: `outOfOrder`][flyway-ooo].
+
+Prefer cherry-picking the same migration from `main` over authoring a new patch-only one.
+
+### 5. Run the release
+
+Once CI is green on the patch branch, follow the [Stable Version](#stable-version) workflow below,
+selecting the patch branch (e.g. `5.0.x`) for the **Branch** parameter.
+
 ## Releasing
 
 ### Stable Version
@@ -11,7 +70,7 @@ To release a new stable version such as `5.7.0` or `5.7.1`:
 1. Ensure the current state in the target branch is ready to be released.
 2. Navigate to the [Release CI] workflow.
 3. Run the workflow with the following parameters:
-   * **Branch**: Select the branch to release from (e.g. `main` for new releases, `5.6.x` for bugfixes).
+   * **Branch**: Select the branch to release from (e.g. `main` for new releases, `5.6.x` for bugfixes, see [Patch Releases](#patch-releases)).
    * **Release version**: Leave empty to use current `SNAPSHOT` version (e.g. `5.7.0-SNAPSHOT` becomes `5.7.0`), or specify a custom version.
    * **Development version**: Leave empty (in which case the patch version will be bumped, e.g. `5.7.0` -> `5.7.1-SNAPSHOT`), or specify a custom next `SNAPSHOT` version.
    * **Dry run**: Enable to test the release process without making any changes.
@@ -28,3 +87,4 @@ To release a prerelease such as `5.7.0-rc.1`:
    * **Development version**: Leave empty (in which case it will be bumped to `5.7.0-rc.2-SNAPSHOT`), or explicitly set to `5.7.0-SNAPSHOT`.
 
 [Release CI]: https://github.com/DependencyTrack/dependency-track/actions/workflows/ci-release.yaml
+[flyway-ooo]: https://documentation.red-gate.com/fd/out-of-order-184127574.html