Track migration to marketplace published branch and main source branch

[aaronpowell]

Summary

Track the repo migration from the current staged -> main publish model to a model where:

• main is the long-term human-authored default/source branch
• marketplace is the long-term published/materialized branch that tools resolve

This should happen in two phases. In the initial phase, the repo should continue operating exactly as it does today for contributors, while also publishing to marketplace. In the later phase, contributor flow moves from staged to main and the legacy publish-only role of main is removed.

Problem

Today contributors are expected to branch from staged and open PRs against staged, while automation materializes plugin content and force-pushes that output to main.

Because GitHub presents main as the default branch, contributors often branch from or target main by mistake. Since main contains materialized plugin content, those PRs become noisy and difficult to review.

The goal is to preserve compatibility for existing clients in the short term, while moving toward a cleaner long-term model where contributors work against main and tools consume published artifacts from marketplace.

Current State

• publish.yml publishes on push to staged, materializes plugin files, and force-pushes to main
• PR-target enforcement rejects PRs against main and directs contributors to staged
• Most PR validation workflows are scoped to staged
• Generated install URLs currently assume published artifacts live on main
• GitHub Pages deploys from workflow-built artifacts; it does not commit generated files back into the repo

Proposed Rollout

Phase 1: Add marketplace without changing contributor flow

Keep the repo operating "as normal":

• contributors still branch from and target staged
• main remains the legacy published branch for older clients
• automation also publishes the materialized output to marketplace

Work in this phase:

• Parameterize source/published refs in publish automation and scripts
• Add marketplace as a second published/materialized branch
• Keep the existing staged -> main publish behavior intact
• Update tool-facing published refs so new consumers can resolve marketplace
• Split links into:
  • source-content links that can stay on the source/default branch
  • published-artifact links that must resolve from marketplace
• Decide whether GitHub Pages continues deploying from the legacy main publication in Phase 1 or switches earlier
• Verify generated outputs are correct in both main and marketplace during the compatibility window
• Update GitHub Copilot CLI to resolve this marketplace from marketplace
• Update VS Code tooling/integration to resolve this marketplace from marketplace
• Update Visual Studio tooling/integration to resolve this marketplace from marketplace
• Coordinate the rollout/release window for those tooling changes so Phase 2 has a clear dependency gate

Phase 2: Move contributor flow from staged to main

After the client transition window:

• Make main the human-authored source/default branch
• Retarget PR validation workflows from staged to main
• Remove or invert automation that warns against PRs targeting main
• Update contributor docs, templates, and remediation text to direct PRs to main
• Retarget website-related validation and deployment orchestration to the final main source-branch flow
• Remove the legacy staged -> main publish path
• Keep marketplace as the only published/materialized branch tools should resolve

Repo Areas Likely To Change

• .github/workflows/publish.yml
• .github/workflows/check-pr-target.yml
• PR validation workflows currently scoped to staged
• .github/workflows/build-website.yml
• .github/workflows/deploy-website.yml
• .github/pull_request_template.md
• CONTRIBUTING.md
• AGENTS.md
• eng/materialize-plugins.mjs
• eng/constants.mjs
• eng/update-readme.mjs
• Generated or contributor-facing docs that encode the old branch contract

Notes / Risks

• Phase 1 should minimize contributor disruption by keeping the existing repo workflow intact
• Not all links need to move; top-level source files and docs can continue to resolve from the source/default branch
• The critical link changes are marketplace metadata and any path that expects materialized plugin contents
• If tool-facing published refs keep pointing at main, clients may continue consuming the legacy branch instead of marketplace
• GitHub Pages is mainly a deployment-trigger/orchestration question, not a generated-files-written-back-to-git problem
• The CLI, VS Code, and Visual Studio changes are cross-repo dependencies and should be tracked here as rollout prerequisites even if implementation happens elsewhere

Acceptance Criteria

• Phase 1 can publish materialized output to both main and marketplace without changing contributor flow
• New tool-facing published refs can resolve from marketplace
• CLI, VS Code, and Visual Studio have shipped support for resolving this marketplace from marketplace
• Phase 2 cleanly moves contributor flow to main
• The final steady state is main for source content and marketplace for published/materialized content