Merge branch 'main' into synapse-pe-approval

.teamcity/components/generated/services.kt

@@ -43,6 +43,7 @@ var services = mapOf(
         "eventgrid" to "EventGrid",
         "eventhub" to "EventHub",
         "firewall" to "Firewall",
+        "fluidrelay" to "Fluid Relay",
         "frontdoor" to "FrontDoor",
         "hdinsight" to "HDInsight",
         "hpccache" to "HPC Cache",

DEVELOPER.md

@@ -3,6 +3,10 @@
 * [Terraform (Core)](https://www.terraform.io/downloads.html) - version 1.x (0.12.x and above are compatible however 1.x is recommended)
 * [Go](https://golang.org/doc/install) version 1.18.x (to build the provider plugin)
 
+## Contributor Guides
+
+A Collection of guides geared towards contributors can be found in the [`/contributing`](https://github.com/hashicorp/terraform-provider-azurerm/tree/main/contributing) directory of this repository.
+
 ### On Windows
 
 If you're on Windows you'll also need:

README.md

@@ -58,6 +58,6 @@ resource "azurerm_virtual_network" "example" {
 * [Learn more about Terraform and the AzureRM Provider on HashiCorp Learn](https://learn.hashicorp.com/collections/terraform/azure-get-started).
 * [Additional examples can be found in the `./examples` folder within this repository](https://github.com/hashicorp/terraform-provider-azurerm/tree/main/examples).
 
-## Developing the Provider
+## Developing & Contributing to the Provider
 
-See [DEVELOPER.md](DEVELOPER.md).
+The [DEVELOPER.md](DEVELOPER.md) file is a basic outline on how to build and develop the provider while more detailed guides geared towards contributors can be found in the [`/contributing`] (https://github.com/hashicorp/terraform-provider-azurerm/tree/main/contributing) directory of this repository.

contributing/README.md

@@ -0,0 +1,48 @@
+# AzureRM Provider Contributor Guides
+
+**First,** thank you for your interest in contributing to the Azure Provider! And if you're unsure or anything, please do reach out for help. You can open a draft pull request (PR) or an issue with what you know or join the [Slack Workspace for Contributors](https://terraform-azure.slack.com) ([Request Invite](https://join.slack.com/t/terraform-azure/shared_invite/enQtNDMzNjQ5NzcxMDc3LWNiY2ZhNThhNDgzNmY0MTM0N2MwZjE4ZGU0MjcxYjUyMzRmN2E5NjZhZmQ0ZTA1OTExMGNjYzA4ZDkwZDYxNDE)) and we'll do our best to guide you in the right direction.
+
+> **Note:** this documentation is a work-in-progress - if you see something that's not quite right or missing, we'd really appreciate a PR!
+
+This contribution guide assumes you have at least a basic understanding of both Go and Terraform itself (for example you know what a Data Source and a Resource are) - more information on those can be found [in the Terraform documentation](https://www.terraform.io/docs/language/index.html).
+
+---
+
+The AzureRM Provider is a Plugin which is invoked by Terraform (Core) and comprised of Data Sources and Resources.
+
+Within the AzureRM Provider, these Data Sources and Resources are grouped into Service Packages - which are logical groupings of Data Sources/Resources based on the Azure Service they're related to.
+
+Each of these Data Sources and Resources has both Acceptance Tests and Documentation associated with each Data Source/Resource - the Acceptance Tests are also located within this Service Package, however the Documentation exists within a dedicated folder.
+
+More granular documentation covers how these fit together - and the most common types of contribution we see:
+
+## Topics
+
+Basics:
+
+* [High-level overview of the Provider](topics/high-level-overview.md).
+* [Building the Provider](topics/building-the-provider.md).
+* [Running the Tests](topics/running-the-tests.md).
+* [Our recommendations for opening a Pull Request](topics/guide-opening-a-pr.md).
+* [Debugging the Provider](topics/debugging-the-provider.md).
+* [Frequently Asked Questions](topics/frequently-asked-questions.md).
+
+Common Topics/Guides:
+
+* [Adding a new Service Package](topics/guide-new-service-package.md).
+* [Adding a new Data Source](topics/guide-new-data-source.md).
+* [Adding a new Resource](topics/guide-new-resource.md).
+* [Adding fields to an existing Data Source](topics/guide-new-fields-to-data-source.md).
+* [Adding fields to an existing Resource](topics/guide-new-fields-to-resource.md).
+* [Opening a PR](topics/guide-opening-a-pr.md).
+
+References:
+
+* [Acceptance Testing](topics/reference-acceptance-testing.md).
+* [Working with Errors](topics/reference-errors.md).
+* [Glossary](topics/reference-glossary.md).
+* [Naming](topics/reference-naming.md).
+
+Maintainer specific:
+
+* [Updates to the Changelog](topics/maintainer-changelog.md).

contributing/topics/building-the-provider.md

@@ -0,0 +1,3 @@
+# Building the Provider
+
+See [DEVELOPER.md](https://github.com/hashicorp/terraform-provider-azurerm/blob/main/DEVELOPER.md).

contributing/topics/debugging-the-provider.md

@@ -0,0 +1,52 @@
+# Debugging the Provider
+
+The provider can be debugged in a number of ways:
+
+- [Adding Log Messages](#logs)
+- [Proxying Traffic](#proxy)
+- [Attaching a Debugger](#debugger-delve)
+
+## Logs
+
+Adding logging is the most basic, and simplest of ways to debug the provider. Log messages can be added with logging statements such as:
+
+```go
+
+// info message
+id, err := parse.SomeResourceId(d.Id())
+if err != nil {
+	return err
+}
+log.Printf("[INFO] %s was not found - removing from state", *id)
+
+// debug message
+log.Printf("[DEBUG] Importing Resource - parsing %q", d.Id())
+```
+
+> **Note:** When logging, lean on the Resource ID Struct (returned from the Parse method above - as shown in the 'info' example above) rather than outputting the Raw Resource ID value (as shown in the debug example above)
+
+These can be viewed by running Terraform (or the Acceptance Test) with logging enabled:
+
+```shell
+$ TF_LOG=INFO terraform apply
+$ TF_LOG=DEBUG make acctests SERVICE='<service>' TESTARGS='-run=<nameOfTheTest>' TESTTIMEOUT='60m'
+```
+
+For more information see [the official Terraform plugin logging documentation](https://www.terraform.io/plugin/log/managing).
+
+## Proxy
+
+A useful step between logging and actual debugging is proxying the traffic through a web debugging proxy such as [Charles Proxy (macOS)](https://www.charlesproxy.com/) or [Fiddler (Windows)](https://www.telerik.com/fiddler). These allow inspection of the web traffic between the provider and Azure to confirm what is actually going across the wire.
+
+You will need to enable HTTPS proxy support (usually by adding a certificate to your system) and then assuming the proxy is running on port `8888`:
+
+```shell
+$ http_proxy=http://localhost:8888 https_proxy=http://localhost:8888 terraform apply
+$ http_proxy=http://localhost:8888 https_proxy=http://localhost:8888 make acctests SERVICE='<service>' TESTARGS='-run=<nameOfTheTest>' TESTTIMEOUT='60m' 
+```
+
+## Debugger (delve)
+
+And finally the most advanced and powerful debugging tool is attaching a debugger such as delve to the provider whilst it is running.
+
+We generally recommend using [Goland](https://jetbrains.com/go) as it provides (amongst other features) native integrations for debugging - see [OpenCredo's blog post](https://opencredo.com/blogs/running-a-terraform-provider-with-a-debugger/) for an example - however it's also possible to use [VSCode and the delve CLI](https://www.terraform.io/plugin/debugging) - configuring these is outside of the scope of this project.

contributing/topics/frequently-asked-questions.md

@@ -0,0 +1,51 @@
+# Frequently Asked Questions
+
+> **Note:** This is a work-in-progress and will be extended over time.
+
+### How can I help?
+
+Great question, we assign labels to each GitHub issue to try and group them, a number of these are relevant for users looking to contribute:
+
+* `good-first-issue` - this label is used to indicate that we think this would make a good issue for users looking to start contributing to the Provider. These are generally small enhancements, such as adding a new field to an existing resource - or documentation changes - and where we're adding this (in more recent issues) we're trying to provide a little context in one of the comments.
+* `help-wanted` - we use this to highlight enhancement issues that are possible and will have a great impact, but that the maintainers are unlikely to reach in the near future.
+
+The [Contributor Readme](../README.md) contains guides on the most common contribution types we see, but if you have any questions not answered in this documentation, please reach out (either in our community slack, or by opening an issue - details can be found in the contributor readme).
+
+### How often is the Provider released?
+
+The estimated dates for each release of the Provider [can be found on the Milestones page](https://github.com/hashicorp/terraform-provider-azurerm/milestones).
+
+As a general rule the Provider is typically released weekly on a Thursday, however this can vary (for example during the winter holidays), as such we recommend checking [the Milestones page](https://github.com/hashicorp/terraform-provider-azurerm/milestones) for the most up to date information.
+
+### My Pull Request has merge conflicts, should I rebase/merge from the `main` branch?
+
+Whilst we do our best to review pull requests as they come in, unfortunately there are cases where it can take some time and merge conflicts can result if they have been sitting for a while. Generally speaking we recommend rebasing/merging from `main` only once a maintainer has taken a look through the PR and explicitly requested it.  
+
+TODO.
+
+### Once a major release is published, will new features and fixes be backported to previous versions?
+
+Generally new features and fixes will only be added to the most recent major version.
+
+Due to the high touch nature of provider development and the extensive regression testing required to ensure stability, maintaining multiple versions of the provider is not sustainable at this time. An exception to this could be a discovered security vulnerability for which backporting may be the most reasonable course of action. These will be reviewed on a case by case basis.
+
+### What do the different GitHub labels mean?
+
+As a general rule the different Azure Services are represented as `service/{serviceName}` - for other labels we're working through adding descriptions which [can be found on the GitHub Labels page for this repository](https://github.com/hashicorp/terraform-provider-azurerm/labels).
+
+### Why was my comment marked as off-topic?
+
+Whilst we thank you for your feedback, we mark comments along the lines of "me too" / "when will this be fixed?" (or generally off-topic comments) as off-topic so that they're hidden by default.
+
+As this repository has a large/active community, we instead ask that you [use a thumbs-up GitHub reaction to the original issue](https://blog.github.com/2016-03-10-add-reactions-to-pull-requests-issues-and-comments/) so that we can prioritise this work without notifying everybody subscribed to the repository.
+
+We appreciate this may be frustrating to have a comment marked as off-topic - when we've not done this we've noticed a number of users regularly adding "+1" / "me too" comments, which ends up causing more distractions for both the maintainers and community in general.
+
+### Why did you close my question?
+
+Whilst we thank you for reaching out, unfortunately we're unable to assist with individual usage questions related to the Azure Provider.
+
+We've closed your issue because we believe it's an issue with the Terraform Configuration being used (or, that the credentials being used to interact with Azure may not have permission to the resources in question), rather than a bug in the Azure Provider.
+
+We instead ask that configuration issues/usage questions related to the Provider are opened [on the Community Discuss forum](https://discuss.hashicorp.com) so that we can keep this repository focused on bugs/feature enhancements related to the Azure Provider.
+