bot-for-go · Oct 28, 2026
@@ -1,3 +1,9 @@
+<!--
+DO NOT EDIT THIS COPY.
+Local edits will be overwritten.
+Source: https://github.com/microsoft/go/blob/microsoft/main/CODE_OF_CONDUCT.md
+-->
+
 # Microsoft Open Source Code of Conduct
 
 This project has adopted the [Microsoft Open Source Code of Conduct](https://opensource.microsoft.com/codeofconduct/).

@@ -0,0 +1,43 @@
+<!--
+DO NOT EDIT THIS COPY.
+Local edits will be overwritten.
+Source: https://github.com/microsoft/go/blob/microsoft/main/CONTRIBUTING.md
+-->
+
+# Contributing
+
+This project welcomes contributions and suggestions.
+
+## Reporting bugs and requesting features
+
+See [SUPPORT.md](SUPPORT.md) for how to report bugs, request features, and ask questions.
+Please search existing issues before opening a new one.
+Report security vulnerabilities privately by following [SECURITY.md](SECURITY.md), rather than opening a public issue.
+
+## Contributing changes
+
+We submit changes to the upstream Go project rather than patching it when possible.
+If your change also applies to upstream Go, see the [Go contribution guide](https://go.dev/doc/contribute).
+
+For changes specific to the Microsoft build of Go:
+
+1. Read the [Developer Guide](eng/doc/DeveloperGuide.md) for repository setup, building, and testing instructions.
+   Changes to the Go source are maintained as patch files; the guide explains how to work with the `go` submodule and generate those patches.
+2. Make your changes and run the relevant tests.
+3. Submit a pull request with a short description of the change and links to any related issues.
+   See [Submitting changes](eng/doc/DeveloperGuide.md#submitting-changes) for details.
+
+## Contributor License Agreement
+
+Most contributions require you to agree to a Contributor License Agreement (CLA) declaring that you have the right to, and actually do, grant us
+the rights to use your contribution. For details, visit https://cla.opensource.microsoft.com.
+
+When you submit a pull request, a CLA bot will automatically determine whether you need to provide
+a CLA and decorate the PR appropriately (e.g., status check, comment). Simply follow the instructions
+provided by the bot. You will only need to do this once across all repos using our CLA.
+
+## Code of Conduct
+
+This project has adopted the [Microsoft Open Source Code of Conduct](https://opensource.microsoft.com/codeofconduct/).
+For more information see the [Code of Conduct FAQ](https://opensource.microsoft.com/codeofconduct/faq/) or
+contact [opencode@microsoft.com](mailto:opencode@microsoft.com) with any additional questions or comments.
@@ -1,3 +1,9 @@
+<!--
+DO NOT EDIT THIS COPY.
+Local edits will be overwritten.
+Source: https://github.com/microsoft/go/blob/microsoft/main/README.md
+-->
+
 # The Microsoft build of Go
 
 Go is an open source programming language that makes it easy to build simple, reliable, and efficient software.
@@ -84,19 +90,8 @@ The [Installation](eng/doc/Installation.md) documentation contains sections desc
 
 ## Contributing
 
-This project welcomes contributions and suggestions.  Most contributions require you to agree to a
-Contributor License Agreement (CLA) declaring that you have the right to, and actually do, grant us
-the rights to use your contribution. For details, visit https://cla.opensource.microsoft.com.
-
-When you submit a pull request, a CLA bot will automatically determine whether you need to provide
-a CLA and decorate the PR appropriately (e.g., status check, comment). Simply follow the instructions
-provided by the bot. You will only need to do this once across all repos using our CLA.
-
-This project has adopted the [Microsoft Open Source Code of Conduct](https://opensource.microsoft.com/codeofconduct/).
-For more information see the [Code of Conduct FAQ](https://opensource.microsoft.com/codeofconduct/faq/) or
-contact [opencode@microsoft.com](mailto:opencode@microsoft.com) with any additional questions or comments.
-
-Please read the [Developer Guide](eng/doc/DeveloperGuide.md) for more information about contributing to this project.
+This project welcomes contributions and suggestions.
+Please read [CONTRIBUTING.md](CONTRIBUTING.md) for contribution guidelines, including the Contributor License Agreement and Code of Conduct.
 
 ## Trademarks
 

@@ -1,3 +1,9 @@
+<!--
+DO NOT EDIT THIS COPY.
+Local edits will be overwritten.
+Source: https://github.com/microsoft/go/blob/microsoft/main/SECURITY.md
+-->
+
 <!-- BEGIN MICROSOFT SECURITY.MD V0.0.5 BLOCK -->
 
 ## Security

@@ -1,3 +1,9 @@
+<!--
+DO NOT EDIT THIS COPY.
+Local edits will be overwritten.
+Source: https://github.com/microsoft/go/blob/microsoft/main/SUPPORT.md
+-->
+
 # Support
 
 For help and questions about the Go programming language and tools, visit the official website: <https://go.dev/>.

@@ -1,3 +1,9 @@
+<!--
+DO NOT EDIT THIS COPY.
+Local edits will be overwritten.
+Source: https://github.com/microsoft/go/blob/microsoft/main/eng/doc/AdditionalFeatures.md
+-->
+
 # Additional Features Provided by the Microsoft build of Go
 
 This document provides a comprehensive overview of all features currently implemented in the Microsoft build of Go that are not part of the official Go distribution.
@@ -48,19 +54,28 @@ The possible values of `ms_tlsx25519` are:
 - `0` disables the X25519 and X25519MLKEM768 TLS groups.
 - `1` (default) enables these groups.
 
-Setting the environment variable `MS_GOTLSMLKEM=0` when building a program changes
-its `tlsmlkem` GODEBUG default to `0`. This disables the default use of the
-X25519MLKEM768, SecP256r1MLKEM768, and SecP384r1MLKEM1024 TLS groups without
-changing the default use of the classical groups, including X25519.
-Other values leave the default unchanged.
-Explicit `godebug` directives in `go.mod` or `go.work` and `//go:debug` directives
-take precedence over this build-time default. Setting `GODEBUG=tlsmlkem=1` at
-runtime re-enables these groups, subject to the other TLS settings.
-Setting `MS_GOTLSMLKEM` only at runtime has no effect.
-This setting applies independently of `ms_tlsprofile` and does not override
-explicit `tls.Config.CurvePreferences`.
-It can also be persisted with `go env -w MS_GOTLSMLKEM=0` and cleared with
-`go env -u MS_GOTLSMLKEM`.
+Microsoft build of Go 1.28 introduces the `MS_GOTLSMLKEM` environment variable, which controls the default use of ML-KEM TLS key exchange in built programs.
+The build-time values are:
+
+- `0`: sets the program's `tlsmlkem` GODEBUG default to `0`.
+- Unset or any other value: leaves the default unchanged.
+
+With `tlsmlkem=0`, programs disable the X25519MLKEM768, SecP256r1MLKEM768, and SecP384r1MLKEM1024 TLS groups by default.
+The default use of classical groups, including X25519, is unchanged.
+This setting applies independently of `ms_tlsprofile` and does not override explicit `tls.Config.CurvePreferences`.
+
+`MS_GOTLSMLKEM` takes effect when the program is built, not when it runs.
+The following command persists the setting for subsequent builds:
+
+```sh
+go env -w MS_GOTLSMLKEM=0
+```
+
+`go env -u MS_GOTLSMLKEM` removes the persisted setting.
+Neither command changes programs that have already been built.
+
+Explicit `godebug` directives in `go.mod` or `go.work` and `//go:debug` directives take precedence over this build-time default.
+At runtime, `GODEBUG=tlsmlkem=1` overrides the built-in default and re-enables the ML-KEM groups, subject to the other TLS settings.
 
 Microsoft build of Go `v1.27.2-2` introduces `ms_tlsmldsacert`, which controls ML-DSA advertisement in the `signature_algorithms_cert` extension.
 The possible values are:

@@ -1,3 +1,9 @@
+<!--
+DO NOT EDIT THIS COPY.
+Local edits will be overwritten.
+Source: https://github.com/microsoft/go/blob/microsoft/main/eng/doc/CrossPlatformCryptography.md
+-->
+
 <!-- This file is generated by eng/_util/cmd/updatecryptodocs. DO NOT EDIT. -->
 
 # Cross-Platform Cryptography in the Microsoft build of Go
@@ -31,7 +37,6 @@ SCOSSL is expected to be used with the default built-in provider enabled as a fa
 ### FreeBSD
 
 Since Go 1.27, the Microsoft build of Go uses the [OpenSSL crypto library](https://docs.openssl.org/3.0/man7/crypto/) on FreeBSD, the same backend as on Linux.
-All FreeBSD architectures are supported with cgo enabled; without cgo, only `amd64` and `arm64` are supported.
 The algorithm support listed in the Linux column of the tables below also applies to FreeBSD.
 
 ### macOS
@@ -40,6 +45,34 @@ On macOS, the Microsoft build of Go uses [CommonCrypto](https://developer.apple.
 CommonCrypto and CryptoKit are shipped with macOS and don't require any additional installation nor configuration.
 Currently macOS 13 and above is supported.
 
+## Cgo
+
+Sometimes, cgo is not available:
+
+* When performing a cross-platform build, a suitable C compiler for cgo is often not available or very difficult to set up correctly.
+* Cgo may be intentionally disabled to simplify the build process, or for security or performance reasons.
+* Cgo may be intentionally disabled to avoid producing a binary that depends on the build system's glibc version. The dependency may be too new, causing the program to fail to run on some target systems. See ["glibc resolution failure on Linux" in the Migration Guide](MigrationGuide.md#glibc-resolution-failure-on-linux).
+
+The Microsoft build of Go attempts to use a cgo-less `systemcrypto` backend when cgo is not enabled, but on some uncommon OS and architecture combinations, this is not supported:
+
+| Target platform | Cgo enabled | Cgo disabled |
+| --- | --- | --- |
+| Linux | ✔️ | ⚠️<sup>1</sup>  |
+| FreeBSD (since Go 1.27) | ⚠️<sup>2,3</sup> | ⚠️<sup>2</sup> |
+| Windows | ✔️ | ✔️ |
+| macOS | ✔️ | ✔️ |
+
+<sup>1</sup> Supported on **amd64**, **arm64**, and [many other architectures](NocgoOpenSSL.md#supported-architectures).
+
+<sup>2</sup> Supported on **amd64** and **arm64** architectures.
+
+<sup>3</sup> Support with cgo for all FreeBSD architectures is [expected in Go 1.27.1](https://github.com/microsoft/go/pull/2477).
+
+> [!IMPORTANT]
+> When using Go 1.26 and targeting Linux or FreeBSD, the table only applies if `GOEXPERIMENT=ms_nocgo_opensslcrypto` is set.
+> Otherwise, cgo is always required.
+> See [No-cgo OpenSSL Backend](NocgoOpenSSL.md) for details.
+
 ## Table legend
 
 The following legend describes the symbols used in the tables to indicate the level of support for each cryptographic algorithm:

@@ -1,3 +1,9 @@
+<!--
+DO NOT EDIT THIS COPY.
+Local edits will be overwritten.
+Source: https://github.com/microsoft/go/blob/microsoft/main/eng/doc/DeveloperGuide.md
+-->
+
 # Developer Guide
 
 This document is a guide for developers who want to contribute to the Microsoft build of Go repository.