[migration] Transfer SkiaSharp API docs from mono to dotnet

[mattleibow]

Parent tracker: mono/SkiaSharp#4959

Summary

Transfer mono/SkiaSharp-API-docs to dotnet/SkiaSharp-API-docs without interrupting the API-doc writer, Microsoft Learn/OpenPublishing builds, PoliCheck/CLA validation, main -> live publication, Learn feedback, or the parent SkiaSharp docs-submodule update.

Known identity

• Repository ID: 175654027
• Default branch: main
• Publication branch: live
• Expected destination: dotnet/SkiaSharp-API-docs
• No GitHub Pages site

Existing baseline to resolve

The Auto API Docs Writer currently has a pre-existing failure streak in its regenerate-stubs path. This must be resolved or explicitly baselined before transfer.

• Diagnose the regenerate-stubs failure.
• Resolve or document open automation PRs.
• Resolve or intentionally retain workflow-failure issues.
• Decide whether Auto-merge Docs should be re-enabled or retired.
• Record one green writer run before the migration freeze.

Phase 1: pre-move repository work

Make repository identities portable

• Define one source-level skiasharp_repository value for writer checkout/clone operations.
• Make workflow steps consume that single value.
• Temporarily allow both old and destination main/docs repositories in gh-aw guards.
• Regenerate auto-api-docs-writer.lock.yml from the source workflow.
• Review the generated lock for expected checkout and policy changes only.
• Modernize active docs.microsoft.com links to learn.microsoft.com.
• Keep historical source links unchanged.

Coordinate the parent repository

• Change the parent SkiaSharp docs submodule branch declaration from master to main.
• Make the parent's docs sync PR text derive the repository from .gitmodules.
• Prepare the parent .gitmodules URL canonicalization for transfer day.
• Update parent contributor templates, docs, skills, CI registry, and dashboards after transfer.

Phase 2: pre-move infrastructure

OpenPublishing and Microsoft Learn

• Export the two active OpenPublishing webhook configurations.
• Identify the Microsoft Learn/OpenPublishing owner for repository registration changes.
• Confirm the existing internal repository registration/GUID can be updated rather than recreated.
• Prepare push and PR webhook validation.
• Prepare OpenPublishing build/status callback validation.
• Prepare production live branch ingestion validation.
• Prepare Learn feedback validation.

GitHub settings and Apps

• Export branch protection and required status contexts: OpenPublishing.Build, license/cla, and PoliCheck Scan where required.
• Export direct collaborators and existing access.
• Define destination team ownership and least-privilege access.
• Export Actions policy, token defaults, workflow enabled state, Apps, custom properties, secret/variable names, and hooks.
• Install/authorize OpenPublishing, PoliCheck, CLA, Copilot/gh-aw, and code-review Apps in dotnet.
• Grant destination access to inherited gh-aw secrets/variables.
• Apply destination security configuration manually.

Phase 3: move window

• Freeze the writer, auto-merge, and main -> live publication.
• Ensure no automation/write-api-docs update is in flight.
• Record final main and live SHAs, open PRs, required checks, and webhook state.
• Confirm dotnet/SkiaSharp-API-docs is available.
• Transfer the repository.
• Confirm repository ID remains 175654027.
• Apply destination teams, protections/rulesets, Apps, security config, and properties.
• Update Docfx feedback repository to dotnet/SkiaSharp-API-docs.
• Update the feedback issue URL to the destination repository.
• Change the writer's SkiaSharp source to dotnet/SkiaSharp after the main repo exists.
• Compile the workflow with destination-only guards after access is proven.
• Update OpenPublishing/Learn repository registration and validate webhook delivery.
• Keep the old namespace unused.

Phase 4: post-move validation

Run the complete chain in order:

• Manually dispatch Auto API Docs Writer.
• Regenerate API stubs successfully.
• Complete the agent phase successfully.
• Push/update the automation branch.
• Create/update the docs PR.
• Receive OpenPublishing.Build.
• Receive PoliCheck Scan.
• Receive license/cla.
• Complete the expected merge/auto-merge path.
• Create and merge the main -> live PR.
• Confirm production Microsoft Learn pages update.
• Use a Learn feedback link and confirm it creates an issue in dotnet/SkiaSharp-API-docs.
• Run the parent SkiaSharp docs-submodule sync.
• Confirm the parent PR points at the destination docs commit.
• Confirm old and new repository web/Git URLs work.
• Re-enable schedules only after the full chain passes.

Proposed sub-issues

• Restore a green API Docs Writer baseline.
• Make the API Docs Writer source repository configurable.
• Prepare OpenPublishing and Learn for dotnet/SkiaSharp-API-docs.
• Update SkiaSharp parent docs-submodule configuration.
• Validate API docs publication after transfer.

Completion criteria

• dotnet/SkiaSharp-API-docs has repository ID 175654027.
• The writer, checks, publication, Learn feedback, and parent submodule chain pass.
• main and live are intact.
• Destination Apps/teams/policy are active.
• mono/SkiaSharp-API-docs remains unused and redirects continue to work.