From 35927bb327e23c0f4ab4bd8d06d2d5f8242d79a6 Mon Sep 17 00:00:00 2001
From: Matt White <16320656+matt-FFFFFF@users.noreply.github.com>
Date: Tue, 25 Jun 2024 12:54:10 +0100
Subject: [PATCH] docs: update docs with FAQ on roadmap and banner for upcoming
 breaking changes (#1008)

---
 README.md                               | 11 +++++++++++
 _README_header.md                       | 11 +++++++++++
 docs/wiki/Frequently-Asked-Questions.md | 10 ++++++++++
 3 files changed, 32 insertions(+)

diff --git a/README.md b/README.md
index 5af307f6e..c909b6acf 100644
--- a/README.md
+++ b/README.md
@@ -15,6 +15,17 @@ Detailed information about how to use, configure and extend this module can be f
 - [Frequently Asked Questions](https://github.com/Azure/terraform-azurerm-caf-enterprise-scale/wiki/Frequently-Asked-Questions)
 - [Troubleshooting](https://github.com/Azure/terraform-azurerm-caf-enterprise-scale/wiki/Troubleshooting)
 
+## ‼ Notice of upcoming breaking changes
+
+We are planning to make some breaking changes to the module in the next release (Q4 2024).
+
+- Module defaults will updated to deploy zone redundant SKUs by default - this applies to:
+  - Firewall
+  - Public IP
+  - Virtual Network Gateway
+
+We will publish guidance on how to avoid re-deployment of existing resources nearer the time.
+
 ## Overview
 
 The [Azure landing zones Terraform module](https://registry.terraform.io/modules/Azure/caf-enterprise-scale/azurerm/latest) is designed to accelerate deployment of platform resources based on the [Azure landing zones conceptual architecture](https://learn.microsoft.com/azure/cloud-adoption-framework/ready/landing-zone#azure-landing-zone-conceptual-architecture) using Terraform.
diff --git a/_README_header.md b/_README_header.md
index b6a8e0c56..c75d6a732 100644
--- a/_README_header.md
+++ b/_README_header.md
@@ -14,6 +14,17 @@ Detailed information about how to use, configure and extend this module can be f
 - [Frequently Asked Questions](https://github.com/Azure/terraform-azurerm-caf-enterprise-scale/wiki/Frequently-Asked-Questions)
 - [Troubleshooting](https://github.com/Azure/terraform-azurerm-caf-enterprise-scale/wiki/Troubleshooting)
 
+## ‼ Notice of upcoming breaking changes
+
+We are planning to make some breaking changes to the module in the next release (Q4 2024).
+
+- Module defaults will updated to deploy zone redundant SKUs by default - this applies to:
+  - Firewall
+  - Public IP
+  - Virtual Network Gateway
+
+We will publish guidance on how to avoid re-deployment of existing resources nearer the time.
+
 ## Overview
 
 The [Azure landing zones Terraform module](https://registry.terraform.io/modules/Azure/caf-enterprise-scale/azurerm/latest) is designed to accelerate deployment of platform resources based on the [Azure landing zones conceptual architecture](https://learn.microsoft.com/azure/cloud-adoption-framework/ready/landing-zone#azure-landing-zone-conceptual-architecture) using Terraform.
diff --git a/docs/wiki/Frequently-Asked-Questions.md b/docs/wiki/Frequently-Asked-Questions.md
index f2726313e..16c4b050b 100644
--- a/docs/wiki/Frequently-Asked-Questions.md
+++ b/docs/wiki/Frequently-Asked-Questions.md
@@ -45,6 +45,16 @@ In large environments, costs can also increase when large volumes of data are be
 
 To see further guidance regarding costs for Azure landing zones, please refer to our [pricing guidance][alz_pricing] page.
 
+### General questions
+
+#### With the upcoming release of the new Azure Landing Zones [AVM](https://aka.ms/avm) module, what is the future for this module and what should I do today?
+
+The Azure Landing Zones Terraform module (`caf-enterprise-scale`) is still our recommendation for customers looking to accelerate deployments.
+
+We are working on a new set of more focussed modules that can be combined like Lego bricks to achieve the outcome you are looking for. These will be published as AVM modules. However, these are not all ready yet. We will publish guidance on the roadmap (including migration advice) in the coming months.
+
+We do want to reassure customers that the caf-enterprise-scale module will remain supported once we release the new set of modules.
+
  [//]: # (************************)
  [//]: # (INSERT LINK LABELS BELOW)
  [//]: # (************************)