docs: add migration guide

Signed-off-by: Mark Sagi-Kazar <[email protected]>

Author: sagikazarmark

README.md

@@ -19,6 +19,27 @@ structure.
 go get github.com/go-viper/mapstructure/v2
 ```
 
+## Migrating from `github.com/mitchellh/mapstructure`
+
+[@mitchehllh](https://github.com/mitchellh) announced his intent to archive some of his unmaintained projects (see [here](https://gist.github.com/mitchellh/90029601268e59a29e64e55bab1c5bdc) and [here](https://github.com/mitchellh/mapstructure/issues/349)). This is a repository achieved the "blessed fork" status.
+
+You can migrate to this package by changing your import paths in your Go files to `github.com/go-viper/mapstructure/v2`.
+The API is the same, so you don't need to change anything else.
+
+Here is a script that can help you with the migration:
+
+```shell
+sed -i 's/github.com\/mitchellh\/mapstructure/github.com\/go-viper\/mapstructure\/v2/g' $(find . -type f -name '*.go')
+```
+
+If you need more time to migrate your code, that is absolutely fine.
+
+Some of the latest fixes are backported to the v1 release branch of this package, so you can use the Go modules `replace` feature until you are ready to migrate:
+
+```shell
+The repository will not go away and will only be archived
+```
+
 ## Usage & Example
 
 For usage and examples see the [documentation](https://pkg.go.dev/mod/github.com/go-viper/mapstructure/v2).