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

Review configuration – set concelier.storage.enableSemVerStyle to true on all Concelier services.
Confirm batch size – adjust concelier.storage.backfillBatchSize if you need smaller batches for older deployments (default: 250).
Back up – capture a fresh snapshot of the advisory collection or a full MongoDB backup.
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

Verify the new indexes exist:
```
db.advisory.getIndexes()
```
You should see advisory_normalizedVersions_pkg_scheme_type and advisory_normalizedVersions_value.
Spot check a few advisories to confirm the top-level normalizedVersions array exists and matches the embedded package data.
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.

2.3 KiB Raw Blame History Unescape Escape