Add comprehensive breaking changes documentation for v6 #674
Conversation
There was a problem hiding this comment.
Pull Request Overview
This PR expands the breaking changes documentation for v6 of the setup-go action, focusing on enhanced Go toolchain management capabilities and improved version resolution behavior. The documentation has been restructured for better clarity and includes practical code examples.
Key changes:
- Added comprehensive documentation for v6's enhanced Go toolchain management, including toolchain directive support and intelligent caching
- Restructured the README with better organization, including Quick Start, Breaking Changes, and Usage sections
- Updated all code examples to use modern Go versions (1.22, 1.23, 1.24) instead of outdated versions
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
| - Wildcards: `1.23.x`, `1.*` | ||
|
|
||
| **Intelligent Caching** | ||
| Cache keys now incorporate toolchain-specific metadata, eliminating version conflicts when switching between golang versions in your workflows. |
There was a problem hiding this comment.
Corrected 'golang' to 'Go' for consistency with the rest of the documentation.
| Cache keys now incorporate toolchain-specific metadata, eliminating version conflicts when switching between golang versions in your workflows. | |
| Cache keys now incorporate toolchain-specific metadata, eliminating version conflicts when switching between Go versions in your workflows. |
|
|
||
| The `check-latest` flag defaults to `false`. Use the default or set `check-latest` to `false` if you prefer stability | ||
| and if you want to ensure a specific Go version is always used. | ||
| If `oldstable` is provided, when current release is 1.23.x, action will resolve version as 1.22.x, where x is the latest patch release. |
There was a problem hiding this comment.
Missing article 'the' before 'current release' and 'action'. Should read: 'If oldstable is provided, when the current release is 1.23.x, the action will resolve version as 1.22.x, where x is the latest patch release.'
| If `oldstable` is provided, when current release is 1.23.x, action will resolve version as 1.22.x, where x is the latest patch release. | |
| If `oldstable` is provided, when the current release is 1.23.x, the action will resolve version as 1.22.x, where x is the latest patch release. |
| ### Check Latest Version | ||
|
|
||
| The check-latest flag defaults to false for stability. This ensures your workflow uses a specific, predictable Go version. | ||
| When check-latest: true: The action verifies if your cached Go version is the latest available. If not, it downloads and uses the newest version. |
There was a problem hiding this comment.
[nitpick] This sentence should be formatted as a bullet point or separate paragraph for consistency with the surrounding content structure. The colon after 'true' creates an awkward sentence break.
| When check-latest: true: The action verifies if your cached Go version is the latest available. If not, it downloads and uses the newest version. | |
| - When `check-latest: true`, the action verifies if your cached Go version is the latest available. If not, it downloads and uses the newest version. |
| #### Automatic Caching | ||
|
|
||
| **Caching in monorepos** | ||
| Default behavior: Searches for go.sum in the repository root and uses its hash for the cache key. |
There was a problem hiding this comment.
For consistency with the rest of the documentation, 'go.sum' should be formatted with backticks as go.sum.
| Default behavior: Searches for go.sum in the repository root and uses its hash for the cache key. | |
| Default behavior: Searches for `go.sum` in the repository root and uses its hash for the cache key. |
| These calls to `actions/go-versions` are made via unauthenticated requests, which are limited to [60 requests per hour per IP](https://docs.github.com/en/rest/overview/resources-in-the-rest-api#rate-limiting). | ||
| If more requests are made within the time frame, then the action leverages the `raw API` to retrieve the version-manifest. This approach does not impose a rate limit and hence facilitates unrestricted consumption. This is particularly beneficial for GHES runners, which often share the same IP, to avoid the quick exhaustion of the unauthenticated rate limit. | ||
| If that fails as well the action will try to download versions directly from https://storage.googleapis.com/golang. | ||
| setup-go comes pre-installed on GHES when Actions is enabled. For dynamic Go version downloads, the action fetches distributions from actions/go-versions on github.com (external to your appliance). |
There was a problem hiding this comment.
The reference 'actions/go-versions' should be formatted as a link or with backticks for consistency. Earlier in the document, it's linked as [go-versions repository](https://github.com/actions/go-versions/...).
| setup-go comes pre-installed on GHES when Actions is enabled. For dynamic Go version downloads, the action fetches distributions from actions/go-versions on github.com (external to your appliance). | |
| setup-go comes pre-installed on GHES when Actions is enabled. For dynamic Go version downloads, the action fetches distributions from the [go-versions repository](https://github.com/actions/go-versions/) on github.com (external to your appliance). |
1 participant
Description:
Expanded Go toolchain improvements section with:
Toolchain directive support details
Advanced version resolution patterns
Intelligent caching behavior
Included code examples for better understanding of go.mod directive handling.
Added migration impact section to highlight benefits of the upgrade
Related issue:
#647
Check list: