Upgrading legacy Terraform providers

I recenty worked on some pretty old Terraform projects (built using v0.10.x I believe). The state on these projects is no longer compatible with v0.13+, which causes errors when trying to run any command. Quite frustrating and the docs don't seem to help much.

Apart from manually downgrading to 0.13, running terraform 0.13upgrade, then upgrading to the latest version, there didn't seem to be any documented solution.

You will likely have some kind of error, similar to the following:

Error: Invalid legacy provider address
This configuration or its associated state refers to the unqualified provider "aws"
You must complete the Terraform 0.13 upgrade process before upgrading to later

If you've already upgraded past terraform 0.13 (likely if you're reading this), then you'll instead need to replace the state values directly. This can be done with the following command:

terraform state replace-provider registry.terraform.io/-/aws hashicorp/aws
terraform state replace-provider registry.terraform.io/-/github hashicorp/aws

Related to this, the Github provider moved from hashicorp namespace to integrations/github. You will need to update your existing state with this new reference. An error message you see may look something like the following:

Warning: Additional provider information from registry
The remote registry returned warnings for registry.terraform.io/hashicorp/github: For users on Terraform 0.13 or greater, this provider has moved to integrations/github. Please update your source in required_providers.

You can resolve this with the following config:

terraform {
  required_providers {
    github = {
      source  = "integrations/github"
      version = "~> 4.10"
    }
  }
}

Once you've made that change, run the following to sync it to your state:

terraform state replace-provider hashicorp/github integrations/github

Now you can run terraform init which should show green, and that it is using integrations/github.

My current output shows the following:

terraform -version
Terraform v0.15.4
on darwin_amd64
+ provider registry.terraform.io/integrations/github v4.10.1