Plan: Create v2 Maintenance Branch for pulumi-azure-native

lively-sprouting-goblet.md

Plan: Create v2 Maintenance Branch for pulumi-azure-native

Overview

Create a v2 branch to enable patching v2.x releases while master continues with v3.x development. The last v2 release was v2.90.0 (commit 9ab68b7632627d5c5a7ad2d1d27dac99712fe429, March 27, 2025).

Key Principle: Minimize differences between v2 and v3 workflows. Both branches use azure-native's custom workflows (not ci-mgmt). A future ci-mgmt migration can be done for both branches together.

Workflow Strategy: Minimal Diff from Master

Master's Current Structure

.github/workflows/
├── master.yml           # Orchestrator: triggers on push to master
├── build-test.yml       # Reusable: called by master.yml and release.yml
├── release.yml          # Orchestrator: triggers on tags v*.*.*
├── publish.yml          # Reusable: called by release.yml
├── version.yml          # Reusable: version calculation
├── weekly-pulumi-update.yml
├── nightly-sdk-generation.yml
└── ... (others)

v2 Branch Structure (Minimal Changes)

.github/workflows/
├── head.yml             # Renamed from master.yml for clarity (triggers on push to v2)
├── build-test.yml       # Unchanged from master (already works for v2 via PROVIDER_VERSION)
├── release.yml          # Modified: v2.*.* tags only, no docs build, make_latest: false
├── publish.yml          # Modified: NPM tag "v2", make_latest: false
├── version.yml          # Unchanged (version comes from git tag)
├── weekly-pulumi-update.yml  # Modified: PROVIDER_VERSION 2.x
└── ... (others unchanged or removed)

Changes Per File

1. master.yml → head.yml (rename + minimal edits)

Changes:

• Rename file: master.yml → head.yml
• Line 5-6: Change trigger from branches: [master] to branches: [v2]
• Env: Change PROVIDER_VERSION: 3.0.0-alpha.0+dev to PROVIDER_VERSION: 2.91.0-alpha.0+dev

Keep same: workflow name name: master (for GitHub UI grouping)

2. build-test.yml (no changes needed)

This reusable workflow already works for v2 because:

• Version comes from input parameter
• Schema selection is driven by Makefile logic based on major version
• No v3-specific hardcoding

3. release.yml (moderate edits)

Changes:

• Line 6: Change tag trigger from v*.*.* to v2.*.* (includes prereleases like v2.91.0-beta.1)
• Remove entire dispatch_docs_build job (lines 38-67 in master)

4. publish.yml (targeted edits)

Changes:

• Add make_latest: false to GitHub release step:

  - name: Create GH Release
    uses: softprops/action-gh-release@v2
    with:
      make_latest: false  # ADD THIS LINE
      ...

• Override NPM tag calculation:

  - name: Calculate tag
    id: tag
    run: echo "tag=v2" >> "$GITHUB_OUTPUT"  # Hardcode "v2" instead of using calculate-npm-tag.sh

5. version.yml (no changes needed)

Version is extracted from git tag, works for any version format.

6. weekly-pulumi-update.yml (minimal edits)

Changes:

• Line ~15: Change PROVIDER_VERSION: 3.0.0-alpha.0+dev to PROVIDER_VERSION: 2.91.0-alpha.0+dev

7. Files to Remove from v2 (optional)

These can be removed as they're not needed for maintenance branch:

• nightly-sdk-generation.yml - no nightly builds for v2
• autorest-scheduled.yml - no spec updates for v2

Implementation Steps

Phase 1: Reset v2 Branch ✓ (Already Done)

• Created v2 branch from v2.90.0 commit
• Pushed to origin
• Fixed OIDC auth tests

Phase 2: Copy Master's Workflows to v2

1. Copy all workflow files from master to v2:

   git checkout v2
   git checkout origin/master -- .github/workflows/

2. Rename master.yml → head.yml:

   git mv .github/workflows/master.yml .github/workflows/head.yml

3. Apply v2-specific edits (see "Changes Per File" above):

   • Edit head.yml: change branch trigger, PROVIDER_VERSION
   • Edit release.yml: change tag trigger, remove dispatch_docs_build
   • Edit publish.yml: add make_latest: false, hardcode NPM tag
   • Edit weekly-pulumi-update.yml: change PROVIDER_VERSION

4. Remove unnecessary workflows (optional):

   git rm .github/workflows/nightly-sdk-generation.yml
   git rm .github/workflows/autorest-scheduled.yml

5. Commit and push:

   git add .github/workflows/
   git commit -m "Configure workflows for v2 maintenance branch"
   git push origin v2

Phase 3: Verify

1. Push triggers head.yml workflow
2. CI builds successfully
3. Schema generates schema-full.json (not schema-default-versions.json)
4. Tests pass

Phase 4: Test Release (Optional)

1. Create prerelease tag: git tag v2.91.0-beta.1 && git push origin v2.91.0-beta.1
2. Verify release.yml triggers and publishes correctly
3. Verify GitHub release has make_latest: false
4. Verify NPM package is tagged as "v2"

v2-Specific Requirements Summary

Aspect	v3 (master)	v2 (maintenance)	How Achieved
Branch trigger	master	v2	Edit head.yml line 5-6
Tag trigger	v*.*.*	v2.*.* (includes prereleases)	Edit release.yml line 6
PROVIDER_VERSION	3.0.0-alpha.0+dev	2.91.0-alpha.0+dev	Edit head.yml, weekly-pulumi-update.yml
GitHub "latest"	Default (true)	make_latest: false	Edit publish.yml
NPM tag	Calculated	Hardcoded "v2"	Edit publish.yml
Docs build	Yes	No	Remove dispatch_docs_build from release.yml
Schema file	schema-default-versions.json	schema-full.json	Automatic (Makefile detects v2)

Success Criteria

• v2 branch has workflow files copied from master
• master.yml renamed to head.yml on v2 branch
• head.yml triggers on push to v2 branch (not master)
• release.yml triggers on v2.. tags (including prereleases)
• release.yml does NOT have dispatch_docs_build job
• publish.yml has make_latest: false
• publish.yml uses NPM tag "v2"
• CI passes on v2 branch push
• Schema generates schema-full.json

Known Remediations

Accidental "latest" marking on GitHub

Fix: Go to GitHub releases → find highest v3 release → Edit → check "Set as latest"

Accidental docs publish for v2

Fix: In pulumi/registry, run:

./tools/resourcedocsgen/resourcedocsgen metadata from-github \
  --providerName=azure-native \
  --repoSlug pulumi/pulumi-azure-native \
  --version="<newest-v3-version>" \
  --publisher Pulumi

Future: ci-mgmt Migration

When ready to adopt ci-mgmt for azure-native:

1. Migrate master branch first
2. Apply same ci-mgmt patterns to v2 branch
3. Both branches stay aligned

This plan intentionally keeps v2 workflows parallel to v3 to make this future migration easier.