website/docs: provider source related clarifications

website/docs/configuration/provider-requirements.html.md

@@ -183,7 +183,15 @@ For example,
 [the official HTTP provider](https://registry.terraform.io/providers/hashicorp/http)
 belongs to the `hashicorp` namespace on `registry.terraform.io`, so its
 source address is `registry.terraform.io/hashicorp/http` or, more commonly, just
-`hashicorp/http`.
+`hashicorp/http`. 
+
+The source address with all three components given explicitly is called the
+provider's _fully-qualified address_. You will see fully-qualified address in
+various outputs, like error messages, but in most cases a simplified display
+version is used. This display version omits the source host when it is the
+public registry, so you may see the shortened version `"hashicorp/random"` instead
+of `"registry.terraform.io/hashicorp/random"`.
+
 
 -> **Note:** If you omit the `source` argument when requiring a provider,
 Terraform uses an implied source address of

website/upgrade-guides/0-13.html.markdown

@@ -45,6 +45,7 @@ Upgrade guide sections:
   * [Special considerations for in-house providers](#in-house-providers)
 * [Destroy-time provisioners may not refer to other resources](#destroy-time-provisioners-may-not-refer-to-other-resources)
 * [Data resource reads can no longer be disabled by `-refresh=false`](#data-resource-reads-can-no-longer-be-disabled-by--refresh-false)
+* [Frequently Asked Questions](#frequently-asked-questions)
 
 ## Before You Upgrade
 
@@ -162,7 +163,7 @@ once (and accept any changes it proposes) before removing any `resource` blocks
 from your configuration after upgrading.
 
 If you are using Terraform Cloud or Terraform Enterprise with the VCS-driven
-workflow (as oposed to CLI-driven runs), refer to
+workflow (as opposed to CLI-driven runs), refer to
 [The UI- and VCS-driven Run Workflow](/docs/cloud/run/ui.html) to learn how
 to manually start a run after you select a Terraform v0.13 release for your
 workspace.
@@ -436,3 +437,46 @@ disable the reading of data resources (declared with `data` blocks).
 ~> Updating the data associated with data resources is crucial to producing an
 accurate plan, and so there is no replacement mechanism in Terraform v0.13
 to restore the previous behavior.
+
+## Frequently Asked Questions
+### Why do I see `-/provider` during init? 
+
+Provider source addresses starting with `registry.terraform.io/-/` are a special
+way Terraform marks legacy addresses where the true namespace is unknown. For
+providers that were automatically-installable in Terraform 0.12, Terraform 0.13
+can automatically determine the new addresses for these using a lookup table in
+the public Terraform Registry. That lookup table is accessed by using the
+special namespace `-`.
+
+When you run `init`, terraform generates a list of required providers based on
+both the configuration and state. Legacy-style providers - such as providers in
+a statefile written with Terraform v0.12 - don't have a namespace, so terraform
+uses the placeholder namespace `-` to query the registry. That is why you may
+see output like this during your first `init`:
+
+```
+- Finding latest version of -/null...
+- Finding latest version of -/random...
+- Finding latest version of hashicorp/null...
+- Finding latest version of hashicorp/random...
+```
+
+Terraform found providers `null` and `random` in the statefile without a
+namespace. Terraform *also* found `hashicorp/null` and `hashicorp/random` in the
+configuration files. Providers in configuration are automatically assumed to be
+default (HashiCorp) providers, while providers found in state are first looked
+up in the registry.
+
+While this does not cause any problems for Terraform, it has been confusing. You
+may circumvent this by using the `terraform state replace-provider` subcommand
+to tell Terraform exactly what provider addresses are required in state.
+Continuing from the example above, the following commands tell Terraform the
+source address for the `null` and `random` providers: 
+
+```
+terraform state replace-provider -- -/random registry.terraform.io/hashicorp/random
+terraform state replace-provider -- -/null registry.terraform.io/hashicorp/null
+```
+
+If you are seeing these messages with errors, and are using in-house or
+locally-installed providers, please see the section on [in-house providers](#in-house-providers).