Azure / Azure/azure-sdk-tools

[APIView] WI-3: Backfill Revisions & Samples

Open
#14,994 2 comments 0 reactions 0 assignees View on GitHub
APIView
Dominant language
C#
Stars
135
Forks
260
Avg merge
3d 1h
Merged PRs (30d)
144

Description

## Goal

Every `APIRevisionListItemModel` and `SamplesRevisionModel` in the database has a non-null `APIVersionId`.

**Area:** Foundation · **Depends on:** WI-1, WI-2 · **Stable alone:** ✅ Yes — backfills FK on historical data; nothing reads it yet

## Deliverables

### Backfill revisions

One-time migration (console command or admin-triggered background job):
1. Fetch all non-deleted revisions where `APIVersionId == null` and `APIRevisionType != PullRequest`
2. Compute `NormalizeVersion(revision.Files[0].PackageVersion)` for each
3. Group by `(reviewId, versionIdentifier)`
4. For each group: find-or-create `APIVersionModel`, set `APIVersionId`, copy approval/release state from revisions to version
5. Handle versionless revisions (JavaScript) per §7.3: label extraction → content-hash grouping → synthetic version

**Idempotent:** Skips revisions where `APIVersionId` is already set. Can be paused and resumed.

### Backfill samples revisions

For each `SamplesRevisionModel` where `APIVersionId == null`: find closest-by-date revision in same review, adopt its `APIVersionId`. Orphaned samples fall back to latest stable version.

### Validation gate

Before downstream WIs (WI-5, WI-7, WI-8, etc.) are flag-flipped, verify:
- `SELECT COUNT(1) FROM c WHERE c.APIVersionId = null AND c.IsDeleted != true` returns 0 for both containers (excluding PR revisions)
- Every `APIVersion` has at least one linked revision

### Tests

- `BackfillMigrationTests.cs` — Grouping by normalized version; approval/release state copied; versionless handling; idempotent re-run
- `SamplesRevisionsManagerTests.cs` — Backfill assigns correct version; orphaned sample fallback

### Documentation

Update `docs/overview.md` §4c to add `APIVersionsManager`. Update `docs/release_approval.md` §5 re: approval migration to version-level.

Contributor guide

Open the contributing guide

Research direction

Start by reading the named BackfillMigrationTests.cs and SamplesRevisionsManagerTests.cs alongside the APIRevisionListItemModel and SamplesRevisionModel requirements, then review the referenced docs/overview.md §4c and docs/release_approval.md §5. Run the backfill and validation queries against representative historical data; done means both backfills are idempotent, versionless and orphaned samples are handled, and the stated validation checks pass.

Written by the indexing model from the issue text.

Assessment

Tech stack
csharp
Domain
backend-api-design, databases, documentation
Issue type
Feature
Difficulty
5/5
Estimated time
Over a week
Activity status
Quiet
Clarity
Mostly clear
Newbie friendliness
35/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.