Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
4 changes: 4 additions & 0 deletions DEVELOPING.md
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
62 changes: 61 additions & 1 deletion RELEASING.md
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand All @@ -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.
Expand All @@ -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
Loading