deprecate-resource-or-field-workflow

name	deprecate-resource-or-field-workflow
description	Workflow for deprecating existing resources, data sources, or fields on the main branch prior to a major release.

deprecate-resource-or-field-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 adding deprecation notices and establishing forwards-compatibility on the main branch prior to a major release.

Prerequisites

• You must be operating on the main branch in the magic-modules root directory.
• You must know the target resource/data source (e.g., google_beyondcorp_app_connector) and the field (or entire resource/data source) to deprecate.
• You must know the replacement path (if applicable) or the reason for deprecation.

---

Execution Steps

1. Context & Guidance

Before beginning implementation, consult:

• docs/content/breaking-changes/make-a-breaking-change.md — Section Add deprecations and warnings to the main branch.
• docs/content/reference/field.md and docs/content/reference/resource.md — Configuration references.
• .agents/knowledge/index.md — General knowledge index.

2. Forwards-Compatibility & Replacement

• Required Fields: If a required field is being deprecated for future removal, make it optional (required: true $\rightarrow$ optional: true in MMv1 YAML or Required: false, Optional: true in Go) so configurations can begin omitting it prior to the major release.
• Renames / Replacements: Ensure the replacement field or resource is implemented, tested, and available on main before or alongside the deprecation.

3. Apply Deprecation Notice

Follow the conventions in docs/content/breaking-changes/make-a-breaking-change.md:

• MMv1 Resources/Fields: Set deprecation_message on the target property or resource in mmv1/products/<product>/<Resource>.yaml.
• Handwritten Resources/Data Sources: Set Deprecated (fields) or DeprecationMessage (resources / data sources) in Go schema (mmv1/third_party/terraform/services/<product>/...) and add deprecation warnings to markdown documentation in website/docs/r/ or website/docs/d/.

4. Run Pre-Gen Checks

• Execute run-pre-gen-checks to verify Go formatting, YAML linting, template validation, and unit tests.

5. Generate Provider & Verify Build

• Execute generate-provider.
• Run make build in the downstream provider repository to verify compilation.

6. Verification Testing

• Invoke qa-test-runner to verify acceptance tests pass (PASS).