| name | major-release-removal-workflow |
| description | Workflow for executing resource, data source, and field removals on a major release feature branch. |
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
- Create a local working branch in
magic-modules based on upstream/${FEATURE_BRANCH}:
git checkout -b remove-<target-name> upstream/$FEATURE_BRANCH
- 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
- Run fast static pre-gen checks: run-pre-gen-checks.
- Generate provider code: generate-provider.
- 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.
