Initial commit (history squashed)

docs/ops/migrations/SEMVER_STYLE.md

@@ -0,0 +1,50 @@
+# 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 `feedser:storage:enableSemVerStyle` is enabled.
+
+## Preconditions
+
+1. **Review configuration** – set `feedser.storage.enableSemVerStyle` to `true` on all Feedser services.
+2. **Confirm batch size** – adjust `feedser.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 Feedser 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 (`feedser.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.Feedser.Storage.Mongo.Tests` (optional but recommended) in CI to confirm
+   the storage suite passes with the feature flag enabled.
+
+## Rollback
+
+Set `feedser.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.