Skip to content

Commit dcaee5d

Browse files
nscuronscuro
authored
Merge pull request #6150 from nscuro/v5-migration-note
Add v5 migration notes
2 parents 30a4567 + c098e56 commit dcaee5d

2 files changed

Lines changed: 314 additions & 0 deletions

File tree

‎README.md‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,6 @@
1+
> [!IMPORTANT]
2+
> **v5 is coming.** Whether you operate or contribute to Dependency-Track, read [V5_MIGRATION.md](./V5_MIGRATION.md).
3+
14
[![Build Status](https://github.com/DependencyTrack/dependency-track/actions/workflows/ci-build.yaml/badge.svg)](https://github.com/DependencyTrack/dependency-track/actions?workflow=CI+Build)
25
[![Codacy Badge](https://app.codacy.com/project/badge/Grade/b2ecd06dab57438a9a55bc4a71c5a8ce)](https://www.codacy.com/gh/DependencyTrack/dependency-track/dashboard?utm_source=github.com&utm_medium=referral&utm_content=DependencyTrack/dependency-track&utm_campaign=Badge_Grade)
36
[![Alpine](https://img.shields.io/badge/built%20on-Alpine-blue.svg)](https://github.com/stevespringett/Alpine)

‎V5_MIGRATION.md‎

Lines changed: 311 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,311 @@
1+
# Migrating to Dependency-Track v5
2+
3+
Dependency-Track v5 is the next major version of the project, previously developed under the codename *Hyades*.
4+
For what is actually new in v5, including architecture, schema, configuration, and API surface, see
5+
[About changes in v5](https://dependencytrack.github.io/docs/next/concepts/changes-in-v5/).
6+
7+
This document covers the GA cutover itself. It describes what changes for operators,
8+
contributors, and downstream consumers as v5 moves to GA, and what your options are for staying on v4.
9+
10+
> [!IMPORTANT]
11+
> Please read this document end-to-end **before** updating any image pin, Helm value, or CI reference.
12+
> The image name changes, and the `:latest` and `:snapshot` tag policies are deliberately conservative
13+
> to avoid moving consumers across a major version without an explicit decision.
14+
15+
## Contents
16+
17+
- [Phases](#phases)
18+
- [What is moving](#what-is-moving)
19+
- [Source repositories](#source-repositories)
20+
- [Container images](#container-images)
21+
- [Tag policy](#tag-policy)
22+
- [`:latest`](#latest)
23+
- [`:snapshot`](#snapshot)
24+
- [v5 tags](#v5-tags)
25+
- [Pin recommendations](#pin-recommendations)
26+
- [Action items by audience](#action-items-by-audience)
27+
- [Operators](#operators)
28+
- [Required action today](#required-action-today)
29+
- [v4 maintenance window](#v4-maintenance-window)
30+
- [After v4 EOL](#after-v4-eol)
31+
- [Migrating to v5](#migrating-to-v5)
32+
- [Helm](#helm)
33+
- [Contributors and PR authors](#contributors-and-pr-authors)
34+
- [If you have an open PR](#if-you-have-an-open-pr)
35+
- [Re-targeting a PR's base branch](#re-targeting-a-prs-base-branch)
36+
- [Moving a local branch to the new repo](#moving-a-local-branch-to-the-new-repo)
37+
- [Forks](#forks)
38+
- [Where things live after cutover](#where-things-live-after-cutover)
39+
- [Issues and discussions on `hyades-*` repos](#issues-and-discussions-on-hyades--repos)
40+
- [ADRs (new in v5)](#adrs-new-in-v5)
41+
- [Historical artifacts](#historical-artifacts)
42+
- [What is **not** changing](#what-is-not-changing)
43+
44+
## Phases
45+
46+
The cutover proceeds in ordered phases. Timing is best-effort and community-driven.
47+
Each phase advances only when its preconditions are met. Do not plan around fixed dates.
48+
49+
> [!IMPORTANT]
50+
> v4 will receive bugfixes and security patches for **at least ~6 months past v5 GA**.
51+
> This minimum is committed, regardless of how cutover-day timing shifts.
52+
53+
| Phase | Precondition | What happens |
54+
|--------------|-------------------------------------------|---------------------------------------------------------------------------------------------------------------------------|
55+
| Announcement | Maintainers agree the cutover is imminent | Public notice. v4 `master` enters freeze on a date named in the notice. |
56+
| Cutover | v5 `5.0.0-rc.1` ready to publish | v4 `master` (both repos) renamed to `v4-master-archived`. v5 imported as `main`. RC published. `hyades-*` repos archived. |
57+
| GA | RC soak completes with no blockers | v5 `5.0.0` GA published. |
58+
| v4 EOL | At least ~6 months elapsed since v5 GA | v4 patches stop. `:snapshot` discontinued. `:latest` flips to v5. |
59+
60+
Each phase is announced ahead of time on the
61+
[GitHub Discussions](https://github.com/DependencyTrack/dependency-track/discussions),
62+
and `#dependency-track` channel in the OWASP Slack.
63+
64+
## What is moving
65+
66+
### Source repositories
67+
68+
| Before (v4 / pre-GA v5) | After (v5 GA onwards) |
69+
|---------------------------------------------|-----------------------------------------------------------------|
70+
| `DependencyTrack/dependency-track` (v4) | `DependencyTrack/dependency-track:4.14.x` (v4) |
71+
| `DependencyTrack/dependency-track:master` | Renamed to `:v4-master-archived` (frozen, no merges accepted) |
72+
| `DependencyTrack/frontend` (v4) | `DependencyTrack/frontend:4.14.x` (v4) |
73+
| `DependencyTrack/frontend:master` | Renamed to `:v4-master-archived` (frozen, no merges accepted) |
74+
| `DependencyTrack/hyades-apiserver` (v5 dev) | `DependencyTrack/dependency-track:main` (v5) |
75+
| `DependencyTrack/hyades-frontend` (v5 dev) | `DependencyTrack/frontend:main` (v5) |
76+
77+
`hyades-apiserver` and `hyades-frontend` are **archived** at cutover. They remain readable.
78+
No new pushes, no new issues, no new PRs.
79+
80+
### Container images
81+
82+
| Before | After |
83+
|----------------------------------------------|----------------------------------------|
84+
| `dependencytrack/hyades-apiserver:<tag>` | `dependencytrack/apiserver:<tag>` |
85+
| `ghcr.io/dependencytrack/hyades-apiserver` | `ghcr.io/dependencytrack/apiserver` |
86+
| `dependencytrack/hyades-frontend:<tag>` | `dependencytrack/frontend:<tag>` |
87+
| `ghcr.io/dependencytrack/hyades-frontend` | `ghcr.io/dependencytrack/frontend` |
88+
89+
v4 images (`dependencytrack/apiserver`, `dependencytrack/frontend`, `dependencytrack/bundled`)
90+
**do not change name**. v4 has always published to these names. Only the pre-GA v5 (`hyades-*`) images are renamed.
91+
92+
> [!NOTE]
93+
> `dependencytrack/bundled` is **v4-only**. There is no v5 equivalent. It follows the v4 lifecycle and stops receiving
94+
> updates at v4 EOL along with the other v4 images.
95+
96+
## Tag policy
97+
98+
`:latest` and `:snapshot` deliberately do **not** flip on the GA date.
99+
This is to prevent unpinned v4 deployments from silently jumping to v5 on the next `docker pull` and breaking.
100+
101+
### `:latest`
102+
103+
| Period | Resolves to |
104+
|-------------------------|----------------------------|
105+
| Today through v4 EOL | Latest v4 release |
106+
| After v4 EOL | Latest v5 release |
107+
108+
If you run `:latest` in production today, **pin to an explicit version before v4 EOL**.
109+
After v4 EOL, `:latest` advances across the major boundary in one pull.
110+
111+
### `:snapshot`
112+
113+
| Tag | Period | Resolves to |
114+
|---------------|----------------------|----------------------------|
115+
| `:snapshot` | Today through v4 EOL | v4 nightly |
116+
| `:snapshot` | After v4 EOL | **Discontinued** |
117+
| `:4-snapshot` | From cutover onwards | v4 nightly (frozen at EOL) |
118+
| `:5-snapshot` | From v5 GA onwards | v5 nightly |
119+
120+
`:snapshot` is **not flipped to v5** at v4 EOL. Migrate to `:4-snapshot` or `:5-snapshot` explicitly.
121+
122+
### v5 tags
123+
124+
| Tag | Resolves to |
125+
|---------------|--------------------------------|
126+
| `:5.x.y` | Exact v5 release. Immutable. |
127+
| `:5.x.y-rc.N` | Exact RC. Immutable. |
128+
| `:5-snapshot` | v5 `main` nightly |
129+
| `:latest` | See [`:latest`](#latest). |
130+
131+
No floating major (`:5`) or minor (`:5.0`) tags are published. This matches v4's tagging surface and steers operators
132+
toward digest or exact-version pins (see [Pin recommendations](#pin-recommendations)).
133+
134+
## Pin recommendations
135+
136+
For production, in order of preference:
137+
138+
1. **Digest pin** (`@sha256:...`). Strongest guarantee. Survives tag mutation, repo deletion, and registry mirroring.
139+
2. **Exact version** (`:4.14.3` or `:5.0.0`). Survives the cutover unchanged.
140+
141+
Use Renovate, Dependabot, or equivalent to bump exact pins on a schedule you control.
142+
143+
Do **not** use `:latest` or `:snapshot` in production. Both move under you without notice.
144+
145+
## Action items by audience
146+
147+
### Operators
148+
149+
#### Required action today
150+
151+
None, **if you pin image tags by an exact version or digest.**
152+
v4 keeps shipping on its existing image names and tags until v4 EOL (~6 months post-v5 GA).
153+
154+
If you currently pull `:latest` or `:snapshot`, switch before v4 EOL:
155+
156+
| Today | Pin to |
157+
|--------------------------------------|-----------------------------------------------|
158+
| `dependencytrack/apiserver:latest` | An exact version (e.g. `:4.14.3`) or a digest |
159+
| `dependencytrack/apiserver:snapshot` | `:4-snapshot` or a digest |
160+
| `dependencytrack/frontend:latest` | An exact version (e.g. `:4.14.3`) or a digest |
161+
| `dependencytrack/frontend:snapshot` | `:4-snapshot` or a digest |
162+
163+
`:4-snapshot` becomes available at cutover. Until then, pin to a digest to escape `:snapshot`.
164+
165+
#### v4 maintenance window
166+
167+
- v4 continues to receive `4.14.x` patch releases. There will be **no further v4 minor releases** (no `4.15.0`).
168+
- Patch cadence is best-effort and community-driven, focused on security and high-severity fixes.
169+
- File v4 bugs against `DependencyTrack/dependency-track` with the `v4` label.
170+
171+
#### After v4 EOL
172+
173+
- No further patches, including for CVEs in v4 itself or its dependencies.
174+
- New issues that apply **only** to v4 are closed with a pointer to v5. Existing `v4`-labeled issues remain as-is
175+
and readable for reference.
176+
177+
#### Migrating to v5
178+
179+
> [!WARNING]
180+
> There is no in-place upgrade. v5 runs on its own PostgreSQL cluster and ingests v4 data via an offline,
181+
> one-shot migrator. Plan downtime accordingly.
182+
183+
- [About changes in v5](https://dependencytrack.github.io/docs/next/concepts/changes-in-v5/) for the architectural,
184+
schema, and configuration deltas.
185+
- [Migrating from v4 to v5](https://dependencytrack.github.io/docs/next/guides/administration/migrating-from-v4/)
186+
for the step-by-step migrator procedure, prerequisites, and post-migration audit checklist.
187+
- [Rehearsing the v4 migration](https://dependencytrack.github.io/docs/next/tutorials/rehearsing-the-v4-migration/)
188+
to dry-run against a production copy before scheduling the cutover.
189+
- [Running v4 and v5 in parallel](https://dependencytrack.github.io/docs/next/guides/administration/running-v4-and-v5-in-parallel/)
190+
for parallel-validation strategies.
191+
192+
#### Helm
193+
194+
The official chart updates together with v5 GA. See [`helm-charts`](https://github.com/DependencyTrack/helm-charts).
195+
Diff your values file against the v5 chart defaults before bumping.
196+
197+
### Contributors and PR authors
198+
199+
> [!IMPORTANT]
200+
> v4 `master` is frozen ahead of cutover and renamed at cutover. Open PRs follow the rename but cannot be merged.
201+
> See [If you have an open PR](#if-you-have-an-open-pr) for what to do.
202+
203+
#### If you have an open PR
204+
205+
Re-target your PR before cutover. If you do not, the PR survives but ends up against `v4-master-archived`,
206+
which accepts no merges. You will have to re-target it yourself afterwards.
207+
208+
**Against `dependency-track:master`** (pre-cutover v4 repo):
209+
210+
- **v4 patch**: re-target the base branch to `4.14.x` (see [re-targeting](#re-targeting-a-prs-base-branch) below).
211+
- **v5-bound**: close and re-open against `hyades-apiserver:main` (pre-cutover) or `dependency-track:main`
212+
(post-cutover). Link the original PR in the new description.
213+
214+
**Against `hyades-apiserver:main` or `hyades-frontend:main`**:
215+
216+
- Pre-cutover: business as usual. Land before cutover if you can.
217+
- At cutover: the repo is archived. Existing PRs are not auto-migrated and cannot be merged.
218+
Re-open against `dependency-track:main` (or `frontend:main`) once v5 GA is published.
219+
220+
#### Re-targeting a PR's base branch
221+
222+
GitHub UI: open the PR, click **Edit** next to the title, pick the new base branch. Works only if the new base lives
223+
in the same repo. For cross-repo moves (`hyades-apiserver` -> `dependency-track`), open a new PR.
224+
225+
#### Moving a local branch to the new repo
226+
227+
After cutover, point your fork and clone at `dependency-track`. The archived `hyades-apiserver` remote still works
228+
read-only but will not accept pushes.
229+
230+
```sh
231+
# 1. Rename your fork on GitHub: Settings -> Repository name -> "dependency-track"
232+
# (GitHub keeps redirects, but update the remote anyway.)
233+
234+
# 2. Update the upstream remote
235+
git remote set-url upstream https://github.com/DependencyTrack/dependency-track.git
236+
237+
# 3. Update your fork remote
238+
git remote set-url origin git@github.com:<you>/dependency-track.git
239+
240+
# 4. Fetch the new default branch and rebase your work
241+
git fetch upstream
242+
git rebase upstream/main
243+
244+
# 5. Push and open the PR against dependency-track:main
245+
git push -u origin <your-branch>
246+
```
247+
248+
> [!NOTE]
249+
> After the rename, `upstream/master` resolves to `upstream/v4-master-archived`.
250+
> That branch is frozen and accepts no merges. Rebase v5-bound work onto
251+
> `upstream/main` and v4-patch work onto `upstream/4.14.x`.
252+
253+
#### Forks
254+
255+
GitHub does **not** auto-rename or auto-archive forks.
256+
257+
- Your fork still exists under its old name and still tracks the archived repo.
258+
- Rename it via **Settings -> Repository name** to keep PRs tidy.
259+
- Branches you pushed before cutover are preserved.
260+
261+
#### Where things live after cutover
262+
263+
| Concern | Location |
264+
|--------------------------------------|-----------------------------------------------------------|
265+
| v5 apiserver code, issues, PRs | `DependencyTrack/dependency-track` (branch `main`) |
266+
| v5 frontend code, issues, PRs | `DependencyTrack/frontend` (branch `main`) |
267+
| v4 maintenance patches | `DependencyTrack/dependency-track` (branch `4.14.x`) |
268+
| `CONTRIBUTING.md`, `SECURITY.md` | `DependencyTrack/dependency-track:main` (root) |
269+
| ADRs | `DependencyTrack/dependency-track:main` under `docs/adr/` |
270+
| Helm charts | `DependencyTrack/helm-charts` (unaffected) |
271+
| User docs | `DependencyTrack/docs` (unaffected) |
272+
273+
#### Issues and discussions on `hyades-*` repos
274+
275+
- Both repos are archived at cutover. Existing issues and discussions stay readable but become read-only.
276+
- Open issues are not auto-migrated. Maintainers will move the ones they judge relevant for v5 to
277+
`DependencyTrack/dependency-track` at their own discretion. No guarantees on which or when.
278+
- If your issue is not moved, and you believe it should be, you have two options:
279+
- Ask a maintainer to move it via OWASP Slack `#dependency-track` or GitHub Discussions, linking the original.
280+
- Re-file on `DependencyTrack/dependency-track` and link the old issue.
281+
- v4 bug reports go on `DependencyTrack/dependency-track` with the `v4` label.
282+
283+
#### ADRs (new in v5)
284+
285+
v5 introduces Architecture Decision Records. Substantial changes now require an ADR that reaches **Accepted**
286+
before the implementation PR merges. v4 had no such requirement. See
287+
`CONTRIBUTING.md#architecture-decision-records` for trigger criteria.
288+
289+
## Historical artifacts
290+
291+
> [!WARNING]
292+
> **The `5.0.0` tag exists in two places with different content.** The archived `hyades-apiserver` repo published
293+
> release tags `5.0.0` through `5.6.0` (and `5.7.0-alpha.X`) during pre-GA development. This was a mistake in hindsight.
294+
> v5 GA restarts numbering at `5.0.0` on `dependency-track:main`. The two are **not** the same artifact. Disambiguate
295+
> by repo and registry path:
296+
>
297+
> | Tag | Source | Meaning |
298+
> |---------|-------------------------------------------------------------|----------------|
299+
> | `5.0.0` | `DependencyTrack/hyades-apiserver` (archived) | Pre-GA, frozen |
300+
> | `5.0.0` | `DependencyTrack/dependency-track` (and `apiserver` images) | v5 GA |
301+
>
302+
> Pre-GA images and source remain pullable from the archived repo for reference. Do not consume them as v5 GA.
303+
304+
## What is **not** changing
305+
306+
To keep expectations grounded:
307+
308+
- The Helm chart repository (`DependencyTrack/helm-charts`) is **not** renamed or archived.
309+
- The documentation repository (`DependencyTrack/docs`) is **not** renamed.
310+
- The project website (`dependencytrack.org`) does not change URL.
311+
- The OWASP project page does not change URL.

0 commit comments

Comments
 (0)