Skip to content

Commit cfb4c8e

Browse files
BigLepCopilot
andauthored
docs: add Go version management policy to CONTRIBUTING.md (#13191)
* docs: add Go version management policy to CONTRIBUTING.md Documents lotus's conservative Go version strategy: - Stay one minor version behind latest Go release - Gradual adoption with ~1 month transition period - Regular patch version updates for security/bug fixes Includes: - Philosophy and rationale behind version strategy - Timeline examples showing upgrade process - Step-by-step instructions for updating Go versions - File purposes and developer notes - Reference to PR #13190 as example implementation This formalizes the existing practices observed in recent Go version updates and provides clear guidance for future updates. * Update CONTRIBUTING.md Co-authored-by: Copilot <[email protected]> * Condensed Go version notes --------- Co-authored-by: Copilot <[email protected]>
1 parent ba5e193 commit cfb4c8e

File tree

1 file changed

+80
-0
lines changed

1 file changed

+80
-0
lines changed

CONTRIBUTING.md

Lines changed: 80 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -9,6 +9,7 @@ Lotus is a universally open project and welcomes contributions of all kinds: cod
99
- [PR Title Conventions](#pr-title-conventions)
1010
- [CHANGELOG Management](#changelog-management)
1111
- [Dependency Management](#dependency-management)
12+
- [Go Version Management](#go-version-management)
1213
- [Markdown Conventions](#markdown-conventions)
1314
- [Table Of Contents](#table-of-contents)
1415
- [Getting Help](#getting-help)
@@ -77,6 +78,85 @@ We enforce that each dependency on an unreleased version of a package is explici
7778
* This is enforced with https://github.com/filecoin-project/lotus/blob/master/.github/workflows/dependency-check.yml
7879
* This enforcement was initially done per [#7131](https://github.com/filecoin-project/lotus/issues/7131).
7980

81+
## Go Version Management
82+
83+
### Philosophy
84+
85+
Lotus follows a conservative Go version strategy to balance stability with access to new features:
86+
87+
- **Stay One Minor Version Behind**: We typically use the Go version that is one minor version behind the latest stable release
88+
- **Gradual Adoption**: When a new Go minor version is released, we continue using the previous version for approximately one month before upgrading
89+
90+
This approach provides:
91+
- **Stability**: Allows time for the Go community to identify and fix issues in new releases
92+
- **Ecosystem Compatibility**: Ensures our dependencies have time to test and adapt to new Go versions
93+
- **Predictable Upgrades**: Contributors and downstream users can anticipate Go version requirements
94+
95+
### Example Timeline
96+
97+
Here's how our Go version policy works in practice:
98+
99+
```
100+
Time t: Latest Go minor version is 1.24.x. We use 1.23.x.
101+
102+
Time t': Go 1.25.x is released. We continue using 1.23.x
103+
(transition period of ~1 month).
104+
105+
Time t'+1 month: Latest Go minor version is 1.25.x. We upgrade to 1.24.x.
106+
```
107+
108+
### Patch Version Updates
109+
110+
Between minor version upgrades, we periodically update to newer patch releases (e.g., 1.23.7 → 1.23.10) to incorporate:
111+
- Security fixes
112+
- Bug fixes
113+
- Performance improvements
114+
115+
These patch updates happen more frequently and are generally lower risk.
116+
117+
### Go Version Update Process
118+
119+
When updating the Go version (either patch or minor), the following files must be updated consistently:
120+
121+
1. **`go.mod`** - The Go language version directive. This specifies the Go language version for module compilation.
122+
2. **`GO_VERSION_MIN`** - Minimum version enforced by the Makefile.
123+
3. **`README.md`** - Documentation and badge (2 locations). This documents requirements for contributors and users.
124+
4. **`Dockerfile`** - Docker base image version. This ensures container builds use the correct Go version.
125+
126+
#### Step-by-Step Process
127+
128+
```bash
129+
# Update go.mod
130+
sed -i 's/go 1.23.7/go 1.23.10/' go.mod
131+
132+
# Update GO_VERSION_MIN
133+
echo "1.23.10" > GO_VERSION_MIN
134+
135+
# Update README.md badge and documentation
136+
sed -i 's/1.23.7/1.23.10/' README.md
137+
138+
# Update Dockerfile
139+
sed -i 's/FROM golang:1.23.7-bullseye/FROM golang:1.23.10-bullseye/' Dockerfile
140+
141+
# Add a changelog entry
142+
143+
go mod tidy
144+
make build
145+
make unittests
146+
```
147+
148+
149+
#### Example Reference
150+
151+
For an example of a Go patch version update, see [PR #13190](https://github.com/filecoin-project/lotus/pull/13190) which updated from Go 1.23.7 to 1.23.10.
152+
153+
### Developer Notes
154+
155+
- **`.go-version`** files are gitignored and developer-specific
156+
- Developers can create local `.go-version` files for their preferred Go version managers
157+
- The formal Go version requirements are documented in the tracked files listed above
158+
- Go version updates should be coordinated changes affecting all relevant files
159+
80160
## Markdown Conventions
81161
We optimize our markdown files for viewing on GitHub. That isn't to say other syntaxes can't be used, but that is the flavor we focus on and at the minimum don't want to break.
82162

0 commit comments

Comments
 (0)