Major Release Removal Workflow

major-release-removal-workflow

Note to AI Agents: You MUST read the YAML frontmatter above first. Only read the rest of this file if the description matches your required task.

This workflow governs removing deprecated resources, data sources, or fields on a major release feature branch (e.g., FEATURE-BRANCH-major-release-8.0.0).

Prerequisites

• You must be operating in the magic-modules repository root directory.
• Determine the target major release version at the start:
  • MAJOR_VERSION: (e.g. 8.0.0)
  • FEATURE_BRANCH="FEATURE-BRANCH-major-release-${MAJOR_VERSION}"
  • UPGRADE_GUIDE="mmv1/third_party/terraform/website/docs/guides/version_${MAJOR_VERSION%%.*}_upgrade.html.markdown"
• You must know the target product, resource/data source, and field (or full resource/data source) to remove.

Execution Steps

1. Pre-Flight Audit via removal-auditor Subagent

Launch the removal-auditor subagent (.agents/agents/removal-auditor/) with the target product, resource/data source, field, and FEATURE_BRANCH.

The subagent will inspect upstream/main (deprecation & replacement checks), upstream/${FEATURE_BRANCH} (sync status), and all repo dependencies, returning a Removal Audit & Blast-Radius Report.

Gating Checks:

• If deprecation is missing on main:
  • Present the blocker to the user.
  • If user directs staging both changes in the session, first execute deprecate-resource-or-field-workflow on main, push the branch, and then proceed with the removal on ${FEATURE_BRANCH}.
• If the release branch is not synced with main: Stop this workflow. Invoke sync-main-to-major-release-branch first.

2. Plan Presentation & Review Checkpoint

Present the subagent's audit report and proposed removal plan to the user as an artifact (schema deletions, template/sample/test cleanup, issue labeler entries, TGC converters, and proposed upgrade guide text).

Do NOT proceed to code modifications until the user approves the plan.

3. Checkout Major Release Branch Across Workspaces

1. Create a local working branch in magic-modules based on upstream/${FEATURE_BRANCH}:

   git checkout -b remove-<target-name> upstream/$FEATURE_BRANCH
   

2. Ensure downstream provider repositories ($GOPATH/src/github.com/hashicorp/terraform-provider-google and terraform-provider-google-beta) are checked out on $FEATURE_BRANCH:

   git -C $GOPATH/src/github.com/hashicorp/terraform-provider-google checkout -B $FEATURE_BRANCH origin/$FEATURE_BRANCH
   git -C $GOPATH/src/github.com/hashicorp/terraform-provider-google-beta checkout -B $FEATURE_BRANCH origin/$FEATURE_BRANCH
   

4. Code Removal & Cleanup

Execute removals across the exact files identified in the approved Removal Audit Report:

• Schema: Delete property/resource YAML in mmv1/products/<product>/... or handwritten Go schema / data sources (mmv1/third_party/terraform/services/<product>/...).
• Custom Templates & Hooks: Remove associated templates in mmv1/templates/terraform/ (expanders, flatteners, hooks, constants, state migrations under state_migrations/).
• Samples & Examples: Remove obsolete sample .tf.tmpl files and test configs.
• Acceptance Tests: Remove deleted fields from test configs and ImportStateVerifyIgnore slices; delete test files for removed resources / data sources.
• Issue Labeler: Remove resource mapping from tools/issue-labeler/labeler/enrolled_teams.yml if the entire resource was removed.
• TGC Converters: Remove converter mappings and IAM registrations from mmv1/third_party/tgc/resource_converters.go.tmpl.
• Documentation: Remove handwritten documentation markdown (docs/r/ or docs/d/) if applicable.

5. Update Version Upgrade Guide

Add entries to ${UPGRADE_GUIDE} following existing entries in that file and guidance in docs/content/breaking-changes/make-a-breaking-change.md:

• Resource Removal: Under ## Resources, add ## Resource: google_<resource> is now removed with migration advice.
• Data Source Removal: Under ## Datasources, add ## Datasource: google_<datasource> is now removed.
• Field Removal: Under ## Resource: google_<resource>, add ### <field> is now removed explaining the removal and replacement argument.

6. Pre-Gen Checks & Code Generation

1. Run fast static pre-gen checks: run-pre-gen-checks.
2. Generate provider code: generate-provider.
3. Verify compilation: Run make build in downstream provider repositories.

7. Verification Testing

Invoke qa-test-runner to run acceptance tests for remaining or adjacent resources to ensure no regressions.