diff --git a/docs/index.md b/docs/index.md
index c1bce3f..0e30eef 100644
--- a/docs/index.md
+++ b/docs/index.md
@@ -58,6 +58,13 @@ By default, the underlying Cloud Foundry client used by the Terraform Cloud Foun
 
 If you're not familiar with Terraform yet, see the [Fundamentals](https://developer.hashicorp.com/terraform/tutorials/cli) section with a lot of helpful tutorials. 
 
+## Migration Guide
+
+The newer v3 APIs have brought several changes to the many oif the resources are created. Some are deprecated and replaced by 
+different resources.
+
+Please refer to the [migration guide](https://github.com/cloudfoundry/terraform-provider-cloudfoundry/tree/main/migration-guide) to help transitioning from the existing [community CF provider](https://github.com/cloudfoundry-community/terraform-provider-cloudfoundry) to the [current CF provider](https://github.com/cloudfoundry/terraform-provider-cloudfoundry) and states the difference between them.
+
 ## Best Practices
 
 For the best experience using the Cloud Foundry provider, we recommend applying the common best practices for Terraform adoption as described in the Hashicorp documentation. For example, see [Phases of Terraform Adoption](https://developer.hashicorp.com/well-architected-framework/operational-excellence/operational-excellence-terraform-maturity).
diff --git a/templates/index.md.tmpl b/templates/index.md.tmpl
index 28dd45f..fcbe000 100644
--- a/templates/index.md.tmpl
+++ b/templates/index.md.tmpl
@@ -33,6 +33,13 @@ By default, the underlying Cloud Foundry client used by the Terraform Cloud Foun
 
 If you're not familiar with Terraform yet, see the [Fundamentals](https://developer.hashicorp.com/terraform/tutorials/cli) section with a lot of helpful tutorials. 
 
+## Migration Guide
+
+The newer v3 APIs have brought several changes to the many oif the resources are created. Some are deprecated and replaced by 
+different resources.
+
+Please refer to the [migration guide](https://github.com/cloudfoundry/terraform-provider-cloudfoundry/tree/main/migration-guide) to help transitioning from the existing [community CF provider](https://github.com/cloudfoundry-community/terraform-provider-cloudfoundry) to the [current CF provider](https://github.com/cloudfoundry/terraform-provider-cloudfoundry) and states the difference between them.
+
 ## Best Practices
 
 For the best experience using the {{.RenderedProviderName}} provider, we recommend applying the common best practices for Terraform adoption as described in the Hashicorp documentation. For example, see [Phases of Terraform Adoption](https://developer.hashicorp.com/well-architected-framework/operational-excellence/operational-excellence-terraform-maturity).