From ed8af66670f5c5e36f5e7f841b80a0137582dde3 Mon Sep 17 00:00:00 2001 From: nscuro Date: Mon, 17 Aug 2026 14:52:49 +0200 Subject: [PATCH] Add upgrade notes for 5.1.0 Signed-off-by: nscuro --- docs/guides/upgrading/.pages | 1 + docs/guides/upgrading/v5.1.0.md | 37 +++++++++++++++++++++++++++++++++ docs/includes/abbreviations.md | 1 + 3 files changed, 39 insertions(+) create mode 100644 docs/guides/upgrading/v5.1.0.md diff --git a/docs/guides/upgrading/.pages b/docs/guides/upgrading/.pages index 5bafbbd3..25c349d4 100644 --- a/docs/guides/upgrading/.pages +++ b/docs/guides/upgrading/.pages @@ -1,6 +1,7 @@ title: Upgrade guides nav: - index.md + - v5.1.0.md - v5.0.0-rc.2.md - v5.0.0-rc.1.md - v0.7.0-alpha.9.md diff --git a/docs/guides/upgrading/v5.1.0.md b/docs/guides/upgrading/v5.1.0.md new file mode 100644 index 00000000..c8cacf9b --- /dev/null +++ b/docs/guides/upgrading/v5.1.0.md @@ -0,0 +1,37 @@ +# Upgrading to v5.1.0 + +!!! warning "The database migration runs longer than usual" + This release rebuilds the global portfolio metrics view and populates a new table tracking package + metadata resolution state. Both scale with portfolio size. Plan for extra startup time, and do not + interrupt the API server while the migration runs. + +* **Database queries now time out**. The API server aborts any single database query that runs longer than 60 seconds. + In earlier versions, queries ran unbounded, so a stuck or runaway query could occupy a connection indefinitely and + exhaust the connection pool. API requests that hit the timeout fail with HTTP status `504`. + + Work that may legitimately exceed the timeout is exempt, notably database migrations and portfolio-wide metrics refreshes. + + Raise the limit with [`dt.datasource.query-timeout-ms`](../../reference/configuration/properties.md#dtdatasourcequery-timeout-ms) + if your deployment reports timeouts for operations that used to succeed. Setting it to `0` disables query timeouts entirely. + Repeated timeouts point at a deeper problem, such as slow I/O, lagging autovacuum, or inefficient query plans. + Report an issue if you have to increase the value permanently. +* **Dependency-Track mirrors KEV catalogs by default**. A new task downloads the CISA and ENISA Known Exploited + Vulnerabilities catalogs daily at 02:00. Dependency-Track turns on both data sources out of the box. Deployments + with restricted egress must allow the feed hosts, or turn off the data sources they cannot reach. Change the + schedule with [`dt.task.kev-mirror.cron`](../../reference/configuration/properties.md#dttaskkev-mirrorcron). + +* **Custom notification templates need updating**. The default templates of the email, Mattermost, Microsoft Teams, + and Slack publishers referenced variables that do not exist in the v5 notification model, so `POLICY_VIOLATION` and + `PROJECT_AUDIT_CHANGE` notifications rendered empty values or failed to publish. Dependency-Track replaces its own + default templates on startup, but templates you cloned or customized keep the broken references. Apply these renames + to affected templates: + + | Old | New | + | --- | --- | + | `subject.policyViolation.policyCondition` | `subject.policyViolation.condition` | + | `subject.violationAnalysis` | `subject.analysis` | + +* **`lastSeen` of affected version attributions now mirrors `firstSeen`**. REST API v1 vulnerability responses expose the + field as `affectedComponents[].affectedVersionAttributions[].lastSeen`. The API server no longer updates it, because + doing so caused large volumes of `UPDATE` queries during mirroring. Treat the field as deprecated. Version 5.2 removes + it, along with its database column. diff --git a/docs/includes/abbreviations.md b/docs/includes/abbreviations.md index bfa33c58..ccaa782a 100644 --- a/docs/includes/abbreviations.md +++ b/docs/includes/abbreviations.md @@ -9,6 +9,7 @@ *[IdP]: Identity Provider *[JVM]: Java Virtual Machine *[KEK]: Key Encryption Key +*[KEV]: Known Exploited Vulnerabilities *[LDAP]: Lightweight Directory Access Protocol *[NIST]: National Institute of Standards and Technology *[NVD]: National Vulnerability Database