Skip to content

Update project documentation structure and clarity #2318

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

Merged
dagood merged 2 commits into from
May 28, 2026
+45 −28
Merged

Update project documentation structure and clarity #2318

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
c79d0cf
Update project documentation structure and clarity
dagood May 27, 2026
90d0820
Explicitly label eng.ms internal links (suggestion)
dagood May 27, 2026
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
41 changes: 21 additions & 20 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -28,32 +28,33 @@ 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.
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:

* [(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.

## Release cycle and policy

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.
We announce each Microsoft build of Go release through the following channels:

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:
* [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).

* [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.
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.

## Download and install

Expand All @@ -76,7 +77,7 @@ The [Installation](eng/doc/Installation.md) documentation contains sections desc
* [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)
* [Binary archive](eng/doc/Installation.md#binary-archive) (`tar.gz` and `zip`)
* [Build from source](eng/doc/Installation.md#build-from-source)

## Contributing
Expand Down
3 changes: 3 additions & 0 deletions SUPPORT.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -4,6 +4,9 @@ For help and questions about the Go programming language and tools, visit the of

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
Expand Down
29 changes: 21 additions & 8 deletions eng/doc/README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,10 +1,23 @@
This directory, `/eng/doc`, contains documents describing the Microsoft
infrastructure used to build Go, in particular any designs that are not obvious
by reading the infrastructure code itself.
# `/eng/doc` - Documentation for the Microsoft build of Go

For cryptography information, see the [CrossPlatformCryptography.md](CrossPlatformCryptography.md) doc.
For dev scenario documentation, see the [DeveloperGuide.md](DeveloperGuide.md) doc.
For telemetry details, see the [Telemetry.md](Telemetry.md) doc.
This directory, `/eng/doc`, contains detailed documents describing the Microsoft build of Go.

The [Downloads.md](Downloads.md) doc contains a table of links to the latest assets for each supported Go release branch.
The [release-branch-links.json](release-branch-links.json) file contains the same data in JSON format suitable for parsing.
> [!IMPORTANT]
> These documents are only actively maintained in the `microsoft/main` branch.
> If you're viewing this file in a release branch, it may be stale.
> [If you're not sure, click here to go to the maintained version of this document.](https://github.com/microsoft/go/blob/microsoft/main/eng/doc/README.md)

## Setup

* [Migration Guide](MigrationGuide.md)
* [Installation](Installation.md)
* [Downloading a binary release](Downloads.md)
* [Developer Guide](DeveloperGuide.md) (for new contributors to the Microsoft build of Go)

## Features

* [Additional Features Provided by the Microsoft build of Go](AdditionalFeatures.md)
* [Cross-Platform Cryptography in the Microsoft build of Go](CrossPlatformCryptography.md)
* [Microsoft Toolset Identification](MicrosoftToolsetIdentification.md)
* [No-cgo OpenSSL Backend](NocgoOpenSSL.md)
* [Telemetry in the Microsoft build of Go](Telemetry.md)
Loading