Add scaffolded 5.0 upgrade guide and hook up flag for testing

.teamcity/components/build_azure.kt

@@ -42,6 +42,5 @@ fun ParametrizedWithType.ConfigureAzureSpecificTestParameters(environment: Strin
     hiddenVariable("env.ARM_TEST_LOCATION", locationsForEnv.primary, "The Primary region which should be used for testing")
     hiddenVariable("env.ARM_TEST_LOCATION_ALT", locationsForEnv.secondary, "The Secondary region which should be used for testing")
     hiddenVariable("env.ARM_TEST_LOCATION_ALT2", locationsForEnv.tertiary, "The Tertiary region which should be used for testing")
-    hiddenVariable("env.ARM_THREEPOINTZERO_BETA", "true", "Opt into the use of 3.0 beta resources")
-    hiddenVariable("env.ARM_FOURPOINTZERO_BETA", "true", "Opt into the use of 4.0 beta resources")
+    hiddenVariable("env.ARM_FIVEPOINTZERO_BETA", "false", "Opt into the 5.0 beta")
 }

internal/features/five_point_oh.go

@@ -3,9 +3,14 @@
 
 package features
 
+import (
+	"os"
+	"strings"
+)
+
 // nolint gocritic
 // DeprecatedInFivePointOh returns the deprecation message if the provider
-// is running in 4.0 mode - otherwise is returns an empty string (such that
+// is running in 5.0 mode - otherwise returns an empty string (such that
 // this deprecation should be ignored).
 // This can be used for the following scenarios:
 //   - Signify resources which will be Deprecated in 5.0, but not Removed (which will happen in a later release).
@@ -18,7 +23,7 @@ func DeprecatedInFivePointOh(deprecationMessage string) string {
 	return deprecationMessage
 }
 
-// FourPointOh returns whether this provider is running in 5.0 mode
+// FivePointOh returns whether this provider is running in 5.0 mode
 // that is to say - the final 5.0 release
 //
 // This exists to allow breaking changes to be piped through the provider
@@ -32,6 +37,13 @@ func FivePointOh() bool {
 //
 // This exists to allow breaking changes to be piped through the provider
 // during the development of 4.x until 5.0 is ready.
+//
+// The environment variable `ARM_FIVEPOINTZERO_BETA` has been added
+// to facilitate testing. But it should be noted that
+// `ARM_FIVEPOINTZERO_BETA` is ** NOT READY FOR PUBLIC USE ** and
+// ** SHOULD NOT BE SET IN PRODUCTION ENVIRONMENTS **
+// Setting `ARM_FIVEPOINTZERO_BETA` will cause irreversible changes
+// to your state.
 func FivePointOhBeta() bool {
-	return FivePointOh() || false
+	return FivePointOh() || strings.EqualFold(os.Getenv("ARM_FIVEPOINTZERO_BETA"), "true")
 }

website/docs/5.0-upgrade-guide.html.markdown

@@ -0,0 +1,70 @@
+---
+layout: "azurerm"
+page_title: "Azure Resource Manager: 5.0 Upgrade Guide"
+description: |-
+Azure Resource Manager: 5.0 Upgrade Guide
+
+---
+
+# Azure Provider
+
+## Azure Provider Version 5.0
+
+TODO
+
+### Pinning your Provider Version
+
+TODO
+
+## What's available in Version 5.0 of the Azure Provider?
+
+* [Removed Resources](#removed-resources)
+* [Removed Data Sources](#removed-data-sources)
+* [Breaking Changes in Resources](#breaking-changes-in-resources)
+* [Breaking Changes in Data Sources](#breaking-changes-in-data-sources)
+
+
+## Removed Resources
+
+Please follow the format in the example below for adding removed resources:
+
+```markdown
+### `azurerm_example_resource`
+
+This deprecated resource has been superseded/retired and has been removed from the Azure Provider.
+```
+
+
+## Removed Data Sources
+
+Please follow the format in the example below for adding removed data sources:
+
+```markdown
+### `azurerm_example_resource`
+
+This deprecated data source has been superseded/retired and has been removed from the Azure Provider.
+```
+
+## Breaking Changes in Resources
+
+Please follow the format in the example below for listing breaking changes in resources:
+
+```markdown
+### `azurerm_example_resource`
+
+* The deprecated `example_old_property` property has been removed in favour of the `example_new_property` property.
+* The deprecated `example_property_with_no_replacement` property has been removed.
+* The `example_property_with_changed_default` property now defaults to `NewDefault`.
+```
+
+
+## Breaking Changes in Data Sources
+
+Please follow the format in the example below for listing breaking changes in data sources:
+
+```markdown
+### `azurerm_example_resource`
+
+* The deprecated `example_old_property` property has been removed in favour of the `example_new_property` property.
+* The deprecated `example_property_with_no_replacement` property has been removed.
+```