Add upgrade notes for 5.1.0

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

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.

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