initial Migration guide

eng/doc/MigrationGuide.md

@@ -0,0 +1,56 @@
+# Migration Guide: Switching to the Microsoft build of Go Toolset
+
+This guide provides step-by-step instructions on migrating from Google's Go distribution to the Microsoft build of Go toolset. It also covers enabling FIPS compliance and common troubleshooting steps.
+
+## Prerequisites
+
+- Ensure your system meets the Microsoft build of Go toolset requirements.
+- Backup your existing Go environment before making changes.
+- Verify that all dependencies are available in the Microsoft build of Go toolset.
+
+## Installing the Microsoft build of Go Toolset
+
+See [Downloading a binary release of the Microsoft build of Go](./Downloads.md) for our up-to-date documentation on downloading the Microsoft build of Go Toolset.
+
+## Enabling FIPS Mode
+
+The Microsoft build of Go toolset provides FIPS-compliant cryptographic operations by leveraging system cryptography on Windows and macOS. On Linux, the toolset leverages OpenSSL's FIPS-compliant implementation.
+
+### FIPS configuration
+
+The toolchain accepts the FIPS-related settings which align with the upstream Go toolchain:
+
+- `GODEBUG=fips140=on` (runtime setting) enables the FIPS 140-3 compliant cryptographic module. Supersedes `GOFIPS=1`, which is now deprecated.
+- `GODEBUG=fips140=only` (runtime setting) acts as `on`, but panics if a non-FIPS 140-3 compliant algorithm is used. This setting is partially supported in Go 1.24, and will be fully supported in Go 1.25.
+- `GOFIPS140=latest` (build setting) sets `GODEBUG=fips140` to `on` by default. Replaces `-tags=requirefips`.
+
+To know more about these settings, please refer to [our FIPS documentation](./fips/README.md).
+
+Note that the Go runtime will automatically enter FIPS mode when running on a FIPS-compliant system, such as [Azure Linux](https://github.com/microsoft/azurelinux) or [Windows](https://learn.microsoft.com/en-us/windows/security/security-foundations/certification/fips-140-validation), so you don't need to set `GODEBUG=fips140=on` on those systems.
+
+## Checking Supported Cryptographic Algorithms
+
+For details on the cryptographic algorithms supported by the Microsoft build of Go toolset across different platforms, refer to [Cross-Platform Cryptography in the Microsoft Build of Go](./CrossPlatformCryptography.md).
+
+## FAQ
+
+1. Why is my FIPS mode not working?
+    Ensure that:
+    - Your system FIPS mode is enabled.
+    - You are using only system-approved cryptographic algorithms.
+    - You have set `GODEBUG=fips140=on`.
+
+1. Will my existing Go code work with Microsoft build of Go?
+
+    Yes, most Go code will work without modification. However, if you rely on custom cryptographic implementations, you may need to adjust your code for FIPS compliance.
+
+1. I'm seeing `panic: opensslcrypto: can't enable FIPS mode for OpenSSL 3.3.2: OSSL_PROVIDER_try_load`
+
+    You are likely building with a Microsoft Build of Go version older than Go `1.23.3-2`, which is the minimum required to support Azure Linux 3.0.
+
+## Support
+For further assistance, please open a [new GitHub issue](https://github.com/microsoft/go/issues/new).
+
+---
+
+By following this guide, you should be able to smoothly transition from Google's Go distribution to the Microsoft build of Go toolset and enable FIPS compliance where necessary.