Skip to content

Sync docs from microsoft/main into microsoft/release-branch.go1.26 #2670

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Closed
bot-for-go wants to merge 1 commit into from
+3,757 −2,392
Closed

Sync docs from microsoft/main into microsoft/release-branch.go1.26 #2670

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
6 changes: 6 additions & 0 deletions CODE_OF_CONDUCT.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -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/).
Expand Down
43 changes: 43 additions & 0 deletions CONTRIBUTING.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -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.
156 changes: 43 additions & 113 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -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.
Expand Down Expand Up @@ -28,140 +34,64 @@ The submodule is updated regularly to the latest commit available in both the up

## Support

This project follows the upstream Go
[Release Policy](https://go.dev/doc/devel/release#policy).
This means we support each major release (1.X) until there are two newer major
releases. A new Go major version is
[released every six months](https://github.com/golang/go/wiki/Go-Release-Cycle),
so each Go major version is supported for about one year.

When upstream Go releases a new minor version (1.X.Y), we release a
corresponding microsoft/go version that may also include fork-specific changes.
This normally happens once a month.

At any time, we may release a new revision (1.X.Y-Z) to fix an issue without waiting for the next upstream minor release.
Revision releases are uncommon.

Each microsoft/go release is announced at the
[Microsoft for Go Developers](https://devblogs.microsoft.com/go/) blog.
Check out the upstream [golang-announce mailing list](https://groups.google.com/g/golang-announce)
for a summary of the changes in each upstream Go version.

See [SUPPORT.md](SUPPORT.md) for more information about reporting bugs, requesting features, and asking questions.

There are a few additional support resources internal to Microsoft:

* [Languages at Microsoft: Go](https://eng.ms/docs/more/languages-at-microsoft/go/articles/overview).
* [A Microsoft-internal email distribution list 📧 (instant join link)](https://idwebelements.microsoft.com/GroupManagement.aspx?Group=golang-announce&Operation=join)
for release announcements.

## Download and install

We build the forked Go toolset with the following list of OS/Arch combinations:

* `linux_amd64`
* `linux_armv6l`
* `linux_arm64`
* `windows_amd64`
* `darwin_amd64`
* `darwin_arm64`

> [!NOTE]
> Cross-compilation to Windows is supported.
> For other OS targets, cgo makes cross-compilation difficult, but it may still be possible.
>
> For example, to build a program for `windows_arm64`, you can cross-compile on a `windows_amd64` or `linux_amd64` host.

Visit the [Migration Guide](eng/doc/MigrationGuide.md) for guidance about how we
recommend migrating existing Go projects to use the Microsoft build of Go. This
guide also helps resolve commonly encountered issues.

The following sections list the ways to get the Microsoft build of Go.

> [!NOTE]
> Don't see an option that works for you? Let us know!
> File a GitHub issue, or comment on an existing issue in this tag:
[![](https://img.shields.io/github/labels/microsoft/go/Area-Acquisition)](https://github.com/microsoft/go/labels/Area-Acquisition)
* [(Microsoft-internal) Languages at Microsoft: Introduction to Go](https://eng.ms/docs/more/languages-at-microsoft/go/articles/overview).
* [(Microsoft-internal) Languages at Microsoft: Get Help with Go](https://eng.ms/docs/more/languages-at-microsoft/go/articles/support).
* Includes internal Microsoft support channels such as an email contact for our team and a community Teams group.

### Docker Container Images
## Release cycle and policy

**[microsoft/go-images](https://github.com/microsoft/go-images)** maintains and
documents container images that are available on Microsoft Artifact Registry.
This project follows the upstream Go [Release Policy](https://go.dev/doc/devel/release#policy).
This means we support each major release (1.X) until there are two newer major releases.
A new Go major version is [released every six months](https://github.com/golang/go/wiki/Go-Release-Cycle), so each Go major version is supported for about one year.

### Azure Linux

The **[Azure Linux](https://github.com/microsoft/azurelinux)** distribution
includes the `golang` package, a build of this fork of Go.

For more information about how to manage the `systemcrypto` migration from 1.24
to 1.25 in Azure Linux 3, see
[the `systemcrypto` section of the Migration Guide](eng/doc/MigrationGuide.md#migration-to-systemcrypto).

### Ubuntu

To install the Microsoft build of Go using an Ubuntu package, first set up the [Linux package repository for Microsoft Products](https://learn.microsoft.com/en-us/linux/packages).
Packages are available in the Ubuntu 22.04 and 24.04 repositories.

After the repository is added, install the Microsoft build of Go by running the following commands:

```bash
sudo apt-get update && sudo apt-get install msft-golang
```

### Binary archive

[Signed builds of Go](https://github.com/microsoft/go/blob/microsoft/main/eng/doc/Downloads.md)
for several platforms are available as `zip` and `tar.gz` files.

### The `go-install.ps1` script
When upstream Go releases a new minor version (1.X.Y), we release a corresponding microsoft/go version that may also include fork-specific changes.
This normally happens once a month.

The [cross-platform `go-install.ps1` script](https://github.com/microsoft/go-infra/tree/main/goinstallscript) installs the Microsoft build of Go.
It can install specific versions or the latest releases.
At any time, we may release a new revision (1.X.Y-Z) to fix an issue without waiting for the next upstream minor release.
Revision releases are uncommon.

If you use Azure Pipelines, try running the script in a [script step](https://learn.microsoft.com/en-us/azure/devops/pipelines/tasks/reference/cmd-line-v2?view=azure-pipelines) and pass the `-AzurePipelinePath` argument to automatically set up `go` in the environment for future steps.
We announce each Microsoft build of Go release through the following channels:

### Build from source
* [Microsoft for Go Developers blog](https://devblogs.microsoft.com/go/).
* [Microsoft-internal email distribution list 📧 (instant join link)](https://idwebelements.microsoft.com/GroupManagement.aspx?Group=golang-announce&Operation=join).

#### Pre-patched source tarball
The Go team announces upstream releases on the [golang-announce mailing list](https://groups.google.com/g/golang-announce).
These announcement emails include a carefully written summary of the changes that may not be found elsewhere.

[The microsoft/go GitHub releases](https://github.com/microsoft/go/releases)
include a source tarball file ending in `.src.tar.gz`. After downloading and
extracting the tar.gz file, build it using the
[upstream instructions](https://go.dev/doc/install/source).
## Download and install

> [!NOTE]
> The `zip` file that GitHub offers for download on the [microsoft/go releases page](https://github.com/microsoft/go/releases) is incomplete: it doesn't include the `go` submodule.
> Make sure to download the `.src.tar.gz` file instead, or [clone the repository using Git and set up the patched submodule](#clone-and-build).
We build the Microsoft build of Go toolset with the following OS/Arch combinations:

#### Clone and build
| OS | `amd64` | `arm64` | `armv6l` |
| --- | :---: | :---: | :---: |
| `darwin` (macOS) | ✓ | ✓ | |
| `linux` | ✓ | ✓ | ✓ |
| `windows` | ✓ | ✓ | |

First, clone this repository using Git and check out the desired tag or commit.
Check out the [Supported Platforms](eng/doc/SupportedPlatforms.md) documentation for detailed platform support information across different Go versions.

If you want to contribute to the Microsoft build of Go project, read the [Developer Guide](eng/doc/DeveloperGuide.md).
It lists the steps we recommend to set up a Microsoft build of Go development environment, execute your first build, run the standard library test suite, and contribute a PR.
Visit the [Migration Guide](eng/doc/MigrationGuide.md) for guidance about how we recommend migrating existing Go projects to use the Microsoft build of Go.
This guide also helps resolve commonly encountered issues.

If you just want to build on your own machine, you may find it more
convenient to use the tools provided by the `eng/run.ps1` script. We use this
script for CI builds. See [eng/README.md](eng/README.md) for more details about
`eng/run.ps1` and other repository infrastructure.
The [Installation](eng/doc/Installation.md) documentation contains sections describing each of the following installation methods:

Once built, the Microsoft build of Go binary is found at `go/bin/go`.
* [Docker Container Images](eng/doc/Installation.md#docker-container-images)
* [Azure Linux](eng/doc/Installation.md#azure-linux)
* [Ubuntu](eng/doc/Installation.md#ubuntu)
* [Azure Pipelines `GoTool@0` task](eng/doc/Installation.md#azure-pipelines-gotool0-task)
* [GitHub Actions `setup-go` action](eng/doc/Installation.md#github-actions-setup-go-action)
* [The `go-install.ps1` script](eng/doc/Installation.md#the-go-installps1-script)
* [Binary archive](eng/doc/Installation.md#binary-archive) (`tar.gz` and `zip`)
* [Build from source](eng/doc/Installation.md#build-from-source)

## 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

Expand Down
6 changes: 6 additions & 0 deletions SECURITY.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -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
Expand Down
51 changes: 30 additions & 21 deletions SUPPORT.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,21 +1,30 @@
# Support

For help and questions about the Go programming language and tools, visit the official website: <https://go.dev/>.

Take a look at the [Migration Guide](eng/doc/MigrationGuide.md) for more information about migrating from the official build of Go to the Microsoft build of Go, specifically.

## How to file issues and get help

This project uses GitHub Issues to track bugs and feature requests. Please search the existing
issues before filing new issues to avoid duplicates. For new issues, [file your bug or
feature request as a new Issue][file].

For help and questions about the microsoft/go project, please [file an issue][file].

If you believe you have found a security vulnerability, please report it privately following the instructions in [SECURITY.md](SECURITY.md).

## Microsoft Support Policy

Support for this project is limited to the resources listed above.

[file]: https://github.com/microsoft/go/issues/new/choose
<!--
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/>.

Take a look at the [Migration Guide](eng/doc/MigrationGuide.md) for more information about migrating from the official build of Go to the Microsoft build of Go, specifically.

> [!TIP]
> Additional support options internal to Microsoft are listed in the ["Support" section of the README file](README.md#support).

## How to file issues and get help

This project uses GitHub Issues to track bugs and feature requests. Please search the existing
issues before filing new issues to avoid duplicates. For new issues, [file your bug or
feature request as a new Issue][file].

For help and questions about the microsoft/go project, please [file an issue][file].

If you believe you have found a security vulnerability, please report it privately following the instructions in [SECURITY.md](SECURITY.md).

## Microsoft Support Policy

Support for this project is limited to the resources listed above.

[file]: https://github.com/microsoft/go/issues/new/choose
Loading
Loading