diff --git a/docs/content/contribute/review-pr.md b/docs/content/contribute/review-pr.md
index 01e3b67f40cd..946348cb174c 100644
--- a/docs/content/contribute/review-pr.md
+++ b/docs/content/contribute/review-pr.md
@@ -17,7 +17,7 @@ This page provides guidelines for reviewing Magic Modules pull requests
1. the features are added in the correct version
* features only available in beta are not included in the GA google provider.
* features added to the GA provider are also included in the beta provider -- beta should be a strict superset of GA.
- 1. no [breaking changes]({{< ref "/develop/breaking-changes" >}}) are introduced without a valid justification.
+ 1. no [breaking changes]({{< ref "/develop/make-a-breaking-change" >}}) are introduced without a valid justification.
1. verify the change actually resolves the linked issues, if any.
1. Check the tests added/modified to ensure that:
1. all fields added/updated in the PR appear in at least one test.
@@ -42,4 +42,4 @@ This page provides guidelines for reviewing Magic Modules pull requests
1. Check documentation to ensure
1. resouce-level and field-level documentation are generated correctly for MMv1-based resource
1. documentation is added manually for handwritten resources.
-1. Check if release notes capture all changes in the PR, and are correctly formatted following the guidance in [write release notes]({{< ref "release-notes" >}}) before merge the PR.
\ No newline at end of file
+1. Check if release notes capture all changes in the PR, and are correctly formatted following the guidance in [write release notes]({{< ref "release-notes" >}}) before merge the PR.
diff --git a/docs/content/develop/breaking-changes.md b/docs/content/develop/breaking-changes.md
deleted file mode 100644
index f0192a635f9f..000000000000
--- a/docs/content/develop/breaking-changes.md
+++ /dev/null
@@ -1,99 +0,0 @@
----
-title: "Understand breaking changes"
-summary: "This page discusses provider versioning, handling of breaking changes, and rare exceptions within Terraform development."
-weight: 12
----
-
-
-# Breaking Changes and Provider Development
-
-## Provider Versioning
-As a provider is developed, resources are added, old resources are updated, and bugs are fixed. These changes are [bundled together as a release](https://github.com/hashicorp/terraform-provider-google/releases/tag/v4.32.0).
-
-Releases are numerically defined with a version number in the form of `MAJOR.MINOR.PATCH`. Here, 'Patch' indicates bug fixes, 'Minor' represents new features, and 'Major' represents significant changes which would be breaking to the customer if committed. Once a release is published, the provider binary is copied to [Hashicorp's provider registry](https://registry.terraform.io/browse/providers).
-
-## Customer Trust
-Terraform authors can write modular configurations, aptly named modules. These are shared within organizations and [online](https://registry.terraform.io/browse/modules). Terraform configurations can specify [provider requirements](https://www.terraform.io/language/providers/requirements), including a [version constraint field](https://www.terraform.io/language/providers/requirements#version-constraints).
-
-The configuration will then [tie these version constraints](https://www.terraform.io/language/expressions/version-constraints) to an approximate minor or exact full version. Maintaining trust and consistency on every `MINOR` or `MAJOR` version upgrade is critical.
-
-If breaking changes are allowed within `MINOR` versions, trust in the provider will be eroded and module creators will not have confidence in provider stability. This diminished trust will eventually lead to customers investing or deploying less to GCP.
-
-## Exceptions to Breaking Changes
-
-While we strive to minimize breaking changes, there are certain exceptions where they become unavoidable. Notably, breaking changes are permissible when existing functionality is demonstrably broken due to an API or provider-level issue. In such cases, the change does not impact users negatively, since there is no instance where the Terraform provider is currently using the affected field or resource correctly.
-
-For example, consider a situation involving the Google provider where an API endpoint we depend on changes its behavior or is deprecated. If the current implementation in the Terraform provider cannot adapt to this change and is thus broken, a breaking change would be necessary to restore the functionality.
-
-## Breaking Changes
-
-Having established that we want to avoid breaking changes, let's delve into what exactly constitutes a breaking change. We'll discuss this under four main categories and the rules within each.
-
-### Provider Configuration Level Breakages
-
-* Top-level behavior such as provider configuration and authentication changes.
-
- Changing fundamental provider behavior (Undetectable)
-
-Including, but not limited to, modification of: authentication, environment variable usage, and constricting retry behavior.
-
-### Resource List Level Breakages
-
-* Resource/datasource naming conventions and entry differences.
-
- Removing or Renaming a Resource
-
-In Terraform, resources should be retained whenever possible. Removal of a resource will result in a configuration breakage wherever a dependency on that resource exists. Renaming or removing resources are functionally equivalent in terms of configuration breakages.
-
-### Resource Level Breakages
-
-* Individual resource breakages like field entry removals or behavior within a resource.
-
- Removing or Renaming a field
-
-In Terraform, fields should be retained whenever possible. Removal of a field will result in a configuration breakage wherever a dependency on that field exists. Renaming or removing a field are functionally equivalent in terms of configuration breakages.
-
- Changing resource ID format (Undetectable)
-
-Terraform uses resource ID to read resource state from the API. Modification of the ID format will break the ability to parse the IDs from any deployments.
-
-
-
-Automation external to our provider may rely on importing resources with a certain format. Removal or modification of existing formats will break this automation.
-
-### Field Level Breakages
-
-* Field-level conventions like attribute changes and naming conventions.
-
- Changing Field Type
-
-While certain Field Type migrations may be supported at a technical level, it's a practice that we highly discourage. We see little value for these transitions vs the risk they impose.
-
- Field becoming Required Field
-
-A field should not become 'Required' as existing configurations may not have this field defined, leading to broken configurations in sequential plans or applies.. If you are adding 'Required' to a field so a block won't remain empty, this can cause two issues. First, if it's a singular nested field, the block may gain more fields later and it's not clear whether the field is actually required so it may be misinterpreted by future contributors. Second, if users are defining empty blocks in existing configurations, this change will break them. Consider these points in admittance of this type of change.
-
- Becoming a Computed only Field
-
-While a field can transition from 'Optional' to 'Optional+Computed', it should not change from 'Required' or 'Optional' to solely 'Computed'. This transition would effectively make the field read-only, thus breaking configs in sequential plan or applies where this field is defined in a configuration.
-
- Optional and Computed to Optional
-
-A field should not transition from 'Computed + Optional' to 'Optional'. During a sequential apply, the Terraform state retains the previously computed value, which won't match the configuration, thus causing a discrepancy.
-
- Adding or Changing a Default Value
-
-Adding a default value where one was not previously declared can work in a very limited subset of scenarios but is an all around 'not good' practice to engage in. Changing a default value will absolutely cause a breakage. The mechanism of break for both scenarios is current terraform deployments now gain a diff with sequential applies where the diff is the new or changed default value.
-
- Growing Minimum Items
-
-'MinItems' cannot grow. Otherwise, existing terraform configurations that don't satisfy this rule will break.
-
- Shrinking Maximum Items
-
-'MaxItems' cannot shrink. Otherwise, existing terraform configurations that don't satisfy this rule will break.
-
-
-
-Modification of the data format (either by the API or manually) will cause a diff in subsequent plans if that field is not Computed. This results in a breakage. API breaking changes are out of scope with respect to provider responsibility but we may make changes in response to API breakages in some instances to provide more customer stability.
-
diff --git a/docs/content/develop/make-a-breaking-change.md b/docs/content/develop/make-a-breaking-change.md
new file mode 100644
index 000000000000..573739188d8f
--- /dev/null
+++ b/docs/content/develop/make-a-breaking-change.md
@@ -0,0 +1,188 @@
+---
+title: "Make a breaking change"
+summary: "Guidance on making a breaking change during a major release"
+weight: 95
+---
+
+# How to make a breaking change
+
+{{< hint info >}}
+**Note:** This page covers the general requirements to make a breaking change
+and may not include exact, comprehensive details on making your change. Breaking
+changes are generally complicated and resource or field specific traits can
+drastically change how they need to be made.
+{{< /hint >}}
+
+## When to (or not to) make a breaking change
+
+Within the Terraform ecosystem, there's a strong expectation of stability
+**including across major versions**. Ecosystem-wide, the community has had
+deeply negative reactions to provider changes with overly-broad impact, and
+too-large changes can delay customers upgrading to adopt new major versions.
+
+In general, we recommend avoiding breaking changes where possible. The
+provider's schema is an API surface relied on by many GCP customers, and users
+have responded negatively to instability in our surface and those of other
+providers.
+
+While the cost to make a change in the provider is relatively cheap, it has
+knock-on effects through the whole ecosystem:
+
+* Modules need to update to adapt to the breaking changes
+* Customers need to update their provider version (and module versions)
+* Terraform assistive tools like [`gcloud terraform vet`](https://cloud.google.com/docs/terraform/policy-validation/quickstart)
+ and 3P tools with provider dependencies like
+ [Config Connector](https://cloud.google.com/config-connector/docs/overview)
+ and [Pulumi GCP Classic](https://www.pulumi.com/registry/packages/gcp/) need
+ to be updated
+
+When breaking changes are made, they must be made within a major release
+(typically yearly) and meet the stringent ecosystem requirements for a breaking
+change, detailed below.
+
+## What counts as a breaking change?
+
+While the general versioning model for providers is captured
+in https://developer.hashicorp.com/terraform/plugin/best-practices/versioning,
+that documentation serves as a baseline for new provider development and not
+guidelines for mature providers like the major cloud providers.
+
+The standard our joint Google & HashiCorp team has developed is that any change
+that requires an end user to modify any previously-valid configuration after a
+provider upgrade is a breaking change, and must happen in a major release. In
+this context "valid" means that a configuration is syntactically correct
+(passes `terraform validate`) and runs in `terraform apply` without returning an
+error. This means that minor corrections are possible such as marking immutable
+fields as immutable if they previously weren't.
+
+There is a single exception to this rule- if a user has managed a resource
+out-of-band from Terraform to enable a new field with a non-default value,
+adding support for the field without handling that case is permissible.
+Terraform will generate a plan that reconciles their state with their live
+configuration.
+
+For example, the following are (a non-exhaustive list of) breaking changes:
+
+* Changing the output format of a field (i.e. from an integer to a string, or
+ the pattern of a structured value)
+* Adding a new required field or changing an existing non-required field to
+ required
+* Removing a field
+* Major behaviour changes to a resource (if configurable, if they are done by
+ default)
+
+Meanwhile, the following are allowed in a minor version:
+
+* Adding a new field
+* Adding update support for a field
+* Removing update support from a field that returned an error in **all cases** a
+ user attempted to update it
+* Marking a field required if *all configurations** that did not specify the
+ field returned an error
+* Major behavioural changes guarded by a flag where the **previous** behaviour
+ is the default
+
+## Making a breaking change
+
+{{< hint info >}}
+**Note:** This section of the document refers to several release versions of the
+provider at once. Breaking changes are made in major releases such as 1.0.0,
+4.0.0, or 4.0.0 (referred to as the "major release" or `N` here) while typical
+provider releases are minor versions, most notably the last minor release of the
+previous major release series such as `2.20.3` for `3.0.0` or `3.90.1`
+for `4.0.0` (referred to as the "last minor release" or `N-1.X` here).
+{{}}
+
+The Terraform provider ecosystem follows the standard that deprecations or
+warnings must be resolvable by end users in the last minor release of the prior
+release series before their removal or change in a major release. Additionally,
+deprecation warnings must be actionable- at the time a deprecation is posted, a
+user must be able to remove the field.
+
+### Renaming a field
+
+The most common type of breaking change is a field rename, and most guidance is
+tuned around that. To perform one, a provider contributor must:
+
+1. Add support for the new field on or before the last minor release of the
+ preceding release series (i.e. version `N-1.X.0`) by contributing to
+ the `main` branch in the magic-modules repo
+2. Mark the old field deprecated on or before the last minor release of the
+ preceding release series (i.e. version `N-1.X.0`) by contributing to
+ the `main` branch in the magic-modules repo
+3. Write an upgrade guide entry in the major release's upgrade guide (such
+ as [this one](https://registry.terraform.io/providers/hashicorp/google/latest/docs/guides/version_5_upgrade)
+ for `5.0.0`) by contributing to the `main` branch in the magic-modules repo
+4. Remove the old field from the major release (i.e. version `N`) in the major
+ release branch in the magic-modules repo
+
+For example, if `google_foobar` has a field `baz` in version `3.80.0` that is
+being replaced by `qux` in `4.0.0`, `qux` must be added on or before `3.90.1`,
+and `baz` must be deprecated within the same window (either at the same time
+as `qux` is added, or afterwards (if added earlier than `3.90.1`), but not
+before).
+
+Example (`google_storage_bucket.bucket_policy_only` -> `google_storage_bucket.uniform_bucket_level_access`)
+* https://github.com/GoogleCloudPlatform/magic-modules/pull/3916 introduced the new field and deprecated the original one in `3.38.0`
+* https://github.com/GoogleCloudPlatform/magic-modules/pull/5340 added the upgrade guide entry and removed the field in `4.0.0`
+* Note: In 4.0.0 the upgrade guide was split between main and the major release branch. Going forward, those changes will be made against main exclusively.
+
+### Removing a field
+
+Removing a field is similar to renaming one, except that a new field doesn't
+need to be introduced:
+
+1. Mark the field deprecated on or before the last minor release of the
+ preceding release series (i.e. version `N-1.X.0`) by contributing to
+ the `main` branch in the magic-modules repo
+2. Write an upgrade guide entry in the major release's upgrade guide (such
+ as [this one](https://registry.terraform.io/providers/hashicorp/google/latest/docs/guides/version_5_upgrade)
+ for `5.0.0`) by contributing to the `main` branch in the magic-modules repo
+3. Remove the field from the major release (i.e. version `N`) in the major
+ release branch in the magic-modules repo
+
+Example (`google_container_cluster.instance_group_urls`)
+* https://github.com/GoogleCloudPlatform/magic-modules/pull/5261 deprecated `instance_group_urls` and filled out the upgrade guide
+* https://github.com/GoogleCloudPlatform/magic-modules/pull/5378 removed the field
+
+### Marking optional fields required
+
+There is no way to message a change to users in advance at the moment, other
+than through the upgrade guide.
+
+1. Write an upgrade guide entry in the major release's upgrade guide (such
+ as [this one](https://registry.terraform.io/providers/hashicorp/google/latest/docs/guides/version_5_upgrade)
+ for `5.0.0`) by contributing to the `main` branch in the magic-modules repo
+2. Mark the field as required in the major release (i.e. version `N`) in the major
+ release branch in the magic-modules repo
+
+Example (`google_app_engine_standard_app_version.entrypoint`)
+* https://github.com/GoogleCloudPlatform/magic-modules/pull/5318 marked the field required and added an upgrade guide entry
+* Note: In 4.0.0 the upgrade guide was split between main and the major release branch. Going forward, those changes will be made against main exclusively.
+
+### Changing default values
+
+Default values in Terraform are used to replace null values in configuration at
+plan/apply time and **do not** respect previously-configured values by the user.
+These changes are often undesirable, as their impact is extremely broad.
+
+When a default is changed, every user that has not specified an explicit value in their configuration will see Terraform propose changing the value of the field **including** if the change will destroy and recreate the resource due to changing an immutable value. Default changes in the provider are comparable in impact to default changes in an API, and modifying examples and modules may achieve the intended effect with a smaller blast radius.
+
+There is no way to message a change to users in advance at the moment, other
+than through the upgrade guide.
+
+1. Write an upgrade guide entry in the major release's upgrade guide (such
+ as [this one](https://registry.terraform.io/providers/hashicorp/google/latest/docs/guides/version_5_upgrade)
+ for `5.0.0`) by contributing to the `main` branch in the magic-modules repo
+2. Mark the new default in the major release (i.e. version `N`) in the major
+ release branch in the magic-modules repo
+
+Example (`google_container_cluster.enable_shielded_nodes`)
+* https://github.com/GoogleCloudPlatform/magic-modules/pull/5263 changed the default value for the field and added an upgrade guide entry
+* Note: In 4.0.0 the upgrade guide was split between main and the major release branch. Going forward, those changes will be made against main exclusively.
+
+## References
+
+* Terraform (Provider) Plugin Development
+ * [Versioning and Changelog](https://developer.hashicorp.com/terraform/plugin/best-practices/versioning)
+ * [SDKv2 Deprecations, Removals, and Renames](https://developer.hashicorp.com/terraform/plugin/sdkv2/best-practices/deprecations)
diff --git a/docs/content/reference/breaking-change-detector.md b/docs/content/reference/breaking-change-detector.md
new file mode 100644
index 000000000000..e508dfa9e606
--- /dev/null
+++ b/docs/content/reference/breaking-change-detector.md
@@ -0,0 +1,140 @@
+---
+title: "Breaking change detector"
+summary: "This page discusses the breaking change detector analysis"
+weight: 45
+aliases:
+- /docs/content/develop/breaking-changes
+
+---
+
+# Breaking change detector
+
+This page documents
+the [breaking change detector](https://github.com/GoogleCloudPlatform/magic-modules/tree/main/tools/breaking-change-detector)
+analysis ran against PRs in this repo.
+
+The breaking change detector is a linter that is able to detect schema-level
+breaking changes that have been proposed in a PR, and will flag them for your
+reviewer. The rules are detailed below. Note that these are not exhaustive, and
+reviewers may determine that a change is a breaking change based on more complex
+criteria than the linter is capable of, such as runtime behaviors or other
+rules.
+
+This page covers the analyses of the detector and is used to provide context for
+contributors. If you're making a breaking change,
+see [make a breaking change](/magic-modules/docs/develop/make-a-breaking-change)
+for details on making a breaking change during a major release development
+period.
+
+## Overriding the detector
+
+By default, the detector blocks merging PRs where a breaking change is detected.
+If overriding it is required in order to bypass an incorrect rule, revert a bad
+change, change an unreleased feature, etc., they can override it by applying
+the `override-breaking-change` label to the PR.
+
+## Types of breakages
+
+### Provider Configuration Level Breakages
+
+* Top-level behavior such as provider configuration and authentication changes.
+
+ Changing fundamental provider behavior (Undetectable)
+
+Including, but not limited to, modification of: authentication, environment
+variable usage, and constricting retry behavior.
+
+### Resource List Level Breakages
+
+* Resource/datasource naming conventions and entry differences.
+
+ Removing or Renaming a Resource
+
+In Terraform, resources should be retained whenever possible. Removal of a
+resource will result in a configuration breakage wherever a dependency on that
+resource exists. Renaming or removing resources are functionally equivalent in
+terms of configuration breakages.
+
+### Resource Level Breakages
+
+* Individual resource breakages like field entry removals or behavior within a
+ resource.
+
+ Removing or Renaming a field
+
+In Terraform, fields should be retained whenever possible. Removal of a field
+will result in a configuration breakage wherever a dependency on that field
+exists. Renaming or removing a field are functionally equivalent in terms of
+configuration breakages.
+
+ Changing resource ID format (Undetectable)
+
+Terraform uses resource ID to read resource state from the API. Modification of
+the ID format will break the ability to parse the IDs from any deployments.
+
+
+
+Automation external to our provider may rely on importing resources with a
+certain format. Removal or modification of existing formats will break this
+automation.
+
+### Field Level Breakages
+
+* Field-level conventions like attribute changes and naming conventions.
+
+ Changing Field Type
+
+While certain Field Type migrations may be supported at a technical level, it's
+a practice that we highly discourage. We see little value for these transitions
+vs the risk they impose.
+
+ Field becoming Required Field
+
+A field should not become 'Required' as existing configurations may not have
+this field defined, leading to broken configurations in sequential plans or
+applies.. If you are adding 'Required' to a field so a block won't remain empty,
+this can cause two issues. First, if it's a singular nested field, the block may
+gain more fields later and it's not clear whether the field is actually required
+so it may be misinterpreted by future contributors. Second, if users are
+defining empty blocks in existing configurations, this change will break them.
+Consider these points in admittance of this type of change.
+
+ Becoming a Computed only Field
+
+While a field can transition from 'Optional' to 'Optional+Computed', it should
+not change from 'Required' or 'Optional' to solely 'Computed'. This transition
+would effectively make the field read-only, thus breaking configs in sequential
+plan or applies where this field is defined in a configuration.
+
+ Optional and Computed to Optional
+
+A field should not transition from 'Computed + Optional' to 'Optional'. During a
+sequential apply, the Terraform state retains the previously computed value,
+which won't match the configuration, thus causing a discrepancy.
+
+ Adding or Changing a Default Value
+
+Adding a default value where one was not previously declared can work in a very
+limited subset of scenarios but is an all around 'not good' practice to engage
+in. Changing a default value will absolutely cause a breakage. The mechanism of
+break for both scenarios is current terraform deployments now gain a diff with
+sequential applies where the diff is the new or changed default value.
+
+ Growing Minimum Items
+
+'MinItems' cannot grow. Otherwise, existing terraform configurations that don't
+satisfy this rule will break.
+
+ Shrinking Maximum Items
+
+'MaxItems' cannot shrink. Otherwise, existing terraform configurations that
+don't satisfy this rule will break.
+
+
+
+Modification of the data format (either by the API or manually) will cause a
+diff in subsequent plans if that field is not Computed. This results in a
+breakage. API breaking changes are out of scope with respect to provider
+responsibility but we may make changes in response to API breakages in some
+instances to provide more customer stability.
+
diff --git a/tools/breaking-change-detector/rules/rule_test.go b/tools/breaking-change-detector/rules/rule_test.go
index 78215892ce23..5c2592277e88 100644
--- a/tools/breaking-change-detector/rules/rule_test.go
+++ b/tools/breaking-change-detector/rules/rule_test.go
@@ -23,7 +23,7 @@ func TestUniqueRuleIdentifiers(t *testing.T) {
func TestMarkdownIdentifiers(t *testing.T) {
// Define the Markdown file path relative to the importer
- mdFilePath := "../../../docs/content/develop/breaking-changes.md"
+ mdFilePath := "../../../docs/content/reference/breaking-change-detector.md"
// Read the Markdown file
mdContent, err := ioutil.ReadFile(mdFilePath)