Add upgrade note about full OSV re-mirroring for v5.0.5

docs/concepts/about-vulnerability-data-sources.md

@@ -38,8 +38,9 @@ The three feeds overlap heavily for open source ecosystems. Most operators do no
 
 ## How Dependency-Track uses the data
 
-Mirroring is a background task. On a configurable schedule and at instance startup, Dependency-Track downloads new and
-changed records from each enabled source and writes them into its own database.
+Mirroring is a background task. On a configurable schedule, Dependency-Track downloads new and changed records from
+each enabled source and writes them into its own database. A first run also happens shortly after the task is scheduled
+initially, so a new deployment starts mirroring without waiting for the schedule.
 
 Vulnerability analysis is a separate process. When you upload a Bill of Materials or trigger analysis, the [internal
 analyzer](../reference/analyzers.md#internal) matches the project's components against the mirrored data already stored

docs/guides/administration/configuring-vulnerability-sources.md

@@ -98,8 +98,9 @@ what each mirror is doing.
 
 ## Scheduling mirror runs
 
-Each source has its own cron property. Mirrors also run on instance startup. To change the schedule, set the
-corresponding property:
+Each source has its own cron property. A mirror also runs once shortly after Dependency-Track schedules it for the
+first time, which happens on a new deployment or when an upgrade introduces the task. Later restarts do not trigger it.
+To change the schedule, set the corresponding property:
 
 - NVD: [`dt.task.nvd-vuln-data-source-mirror.cron`](../../reference/configuration/properties.md#dttasknvd-vuln-data-source-mirrorcron)
 - GitHub advisories:

docs/guides/upgrading/v5.0.5.md

@@ -10,3 +10,13 @@
     | --- | --- |
     | `subject.policyViolation.policyCondition` | `subject.policyViolation.condition` |
     | `subject.violationAnalysis` | `subject.analysis` |
+
+* **The upgrade forces a full OSV mirror**. Dependency-Track converted some OSV version ranges incorrectly,
+  which matched components against vulnerabilities that do not affect them. The upgrade purges the watermarks
+  that the OSV vulnerability data source uses to track incremental progress. Existing OSV data stays in place,
+  but the next mirror run processes the full OSV data set instead of only recent changes,
+  and overwrites the affected records. Expect that run to take longer than usual.
+
+    Corrected data is not available until the OSV mirror runs, which happens daily at 03:00 UTC by default.
+    To get the corrected data sooner, use **Mirror now** as described in
+    [Triggering an initial mirror](../administration/configuring-vulnerability-sources.md#triggering-an-initial-mirror).

docs/reference/configuration/task-scheduler.md

@@ -44,8 +44,8 @@ dt.task.nvd-vuln-data-source-mirror.cron=30 3 * * *
 ## Scheduled tasks
 
 The scheduler ships with the following recurring tasks. Tasks marked with
-[^1] also run once shortly after startup, with a random delay of up to one
-minute.
+[^1] also run once shortly after the scheduler registers them for the first
+time, with a random delay of up to one minute.
 
 | Task                              | Property                                                                                                                | Default cron     | Purpose                                                                                       |
 |-----------------------------------|-------------------------------------------------------------------------------------------------------------------------|------------------|-----------------------------------------------------------------------------------------------|
@@ -69,4 +69,4 @@ minute.
 | Scheduled notification dispatch   | [`dt.task.scheduled-notification-dispatch.cron`](properties.md#dttaskscheduled-notification-dispatchcron)               | `* * * * *`      | Polls for due scheduled notification rules and dispatches them.                               |
 | Telemetry submission[^1]          | [`dt.task.telemetry-submission.cron`](properties.md#dttasktelemetry-submissioncron)                                     | `0 */1 * * *`    | Submits anonymous usage data. See [Telemetry](telemetry.md).                                  |
 
-[^1]: Triggered once on startup with a random delay of up to one minute, then on the configured schedule.
+[^1]: Triggered once when the scheduler first registers the task, with a random delay of up to one minute, then on the configured schedule. Registration happens on a new deployment, or when an upgrade introduces the task. Later restarts do not trigger another run.

docs/reference/datasources/index.md

@@ -11,7 +11,8 @@ sources](../../concepts/about-vulnerability-data-sources.md). For the procedure
 ## Mirrored sources
 
 Dependency-Track can mirror three public sources into its local database. Mirroring runs on a configurable schedule
-(daily by default) and on instance startup. Progress and errors are written to the API server logs.
+(daily by default), and once shortly after Dependency-Track schedules the task for the first time. Progress and errors
+are written to the API server logs.
 
 | Source | Identifier prefix | Matches on |
 |:-------|:------------------|:-----------|