51 lines
2.3 KiB
Markdown
51 lines
2.3 KiB
Markdown
# SemVer Style Backfill Runbook
|
||
|
||
_Last updated: 2025-10-11_
|
||
|
||
## Overview
|
||
|
||
The SemVer style migration populates the new `normalizedVersions` field on advisory documents and ensures
|
||
provenance `decisionReason` values are preserved during future reads. The migration is idempotent and only
|
||
runs when the feature flag `concelier:storage:enableSemVerStyle` is enabled.
|
||
|
||
## Preconditions
|
||
|
||
1. **Review configuration** – set `concelier.storage.enableSemVerStyle` to `true` on all Concelier services.
|
||
2. **Confirm batch size** – adjust `concelier.storage.backfillBatchSize` if you need smaller batches for older
|
||
deployments (default: `250`).
|
||
3. **Back up** – capture a fresh snapshot of the `advisory` collection or a full MongoDB backup.
|
||
4. **Staging dry-run** – enable the flag in a staging environment and observe the migration output before
|
||
rolling to production.
|
||
|
||
## Execution
|
||
|
||
No manual command is required. After deploying the configuration change, restart the Concelier WebService or
|
||
any component that hosts the Mongo migration runner. During startup you will see log entries similar to:
|
||
|
||
```
|
||
Applying Mongo migration 20251011-semver-style-backfill: Populate advisory.normalizedVersions for existing documents when SemVer style storage is enabled.
|
||
Mongo migration 20251011-semver-style-backfill applied
|
||
```
|
||
|
||
The migration reads advisories in batches (`concelier.storage.backfillBatchSize`) and writes flattened
|
||
`normalizedVersions` arrays. Existing documents without SemVer ranges remain untouched.
|
||
|
||
## Post-checks
|
||
|
||
1. Verify the new indexes exist:
|
||
```
|
||
db.advisory.getIndexes()
|
||
```
|
||
You should see `advisory_normalizedVersions_pkg_scheme_type` and `advisory_normalizedVersions_value`.
|
||
2. Spot check a few advisories to confirm the top-level `normalizedVersions` array exists and matches
|
||
the embedded package data.
|
||
3. Run `dotnet test` for `StellaOps.Concelier.Storage.Mongo.Tests` (optional but recommended) in CI to confirm
|
||
the storage suite passes with the feature flag enabled.
|
||
|
||
## Rollback
|
||
|
||
Set `concelier.storage.enableSemVerStyle` back to `false` and redeploy. The migration will be skipped on
|
||
subsequent startups. You can leave the populated `normalizedVersions` arrays in place; they are ignored when
|
||
the feature flag is off. If you must remove them entirely, restore from the backup captured during
|
||
preparation.
|