Skip to content

Commit 664a111

Browse files
ChronosMasterOfAllTimeChronosMasterOfAllTime
authored
Update docs in preparation for v3 rollout (#525)
* WIP: Update docs in preparation for v3 rollout * chore: update readme to match end of support in brew
1 parent 0469056 commit 664a111

3 files changed

Lines changed: 217 additions & 0 deletions

File tree

‎INSTALL.md‎

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -96,9 +96,15 @@ The ZPlug plugin will install and initialise `goenv` and add `goenv` and `goenv-
9696
You can also install goenv using the [Homebrew](http://brew.sh)
9797
package manager for Mac OS X.
9898

99+
**For the current version (v3 - recommended):**
100+
99101
brew update
100102
brew install goenv
101103

104+
**For the legacy version (v2 - for existing deployments):**
105+
106+
brew install goenv@2 && brew link goenv@2
107+
102108
To upgrade goenv in the future, use `upgrade` instead of `install`.
103109

104110
After installation, you'll need to add `eval "$(goenv init -)"` to your profile (as stated in the caveats displayed by Homebrew — to display them again, use `brew info goenv`). You only need to add that to your profile once.

‎README.md‎

Lines changed: 47 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -8,6 +8,8 @@
88
[![Linux](https://img.shields.io/badge/Linux-FCC624?logo=linux&logoColor=black)](https://github.com/go-nv/goenv)
99
[![macOS](https://img.shields.io/badge/macOS-000000?logo=macos&logoColor=F0F0F0)](https://github.com/go-nv/goenv)
1010

11+
> **📢 Version Note:** goenv v3 is now the current stable version. v2 remains available as `goenv@2` for legacy support. See [Version Support Policy](#version-support-policy) below.
12+
1113
goenv aims to be as simple as possible and follow the already established
1214
successful version management model of [pyenv](https://github.com/pyenv/pyenv) and [rbenv](https://github.com/rbenv/rbenv).
1315

@@ -33,6 +35,51 @@ This project was cloned from [pyenv](https://github.com/pyenv/pyenv) and modifie
3335

3436
---
3537

38+
## Version Support Policy
39+
40+
### Current Version (v3.x)
41+
42+
goenv v3 is the current stable release and is recommended for all new installations. It features:
43+
- Complete rewrite from shell scripts to Go-based CLI for improved performance and reliability
44+
- Full backward compatibility with v2
45+
- Active development and feature updates
46+
47+
**Installation:**
48+
```bash
49+
# Homebrew (macOS/Linux)
50+
brew install goenv
51+
52+
# Manual installation
53+
git clone https://github.com/go-nv/goenv.git ~/.goenv
54+
```
55+
56+
### Legacy Version (v2.x)
57+
58+
goenv v2 is maintained for legacy support with a **minimum 2-year commitment** (until December 2028 or End of Support, whichever comes first). During this period, v2 will receive:
59+
- Security patches and critical bug fixes
60+
- Maintenance through the `master` branch
61+
- Support for existing production deployments
62+
63+
**When to use v2:**
64+
- AWS CodeBuild and CI systems with existing v2 dependencies
65+
- Production systems requiring additional validation time before migrating to v3
66+
- Docker containers that haven't yet been updated to v3
67+
68+
**Installation:**
69+
```bash
70+
# Homebrew - versioned formula
71+
brew install goenv@2 && brew link goenv@2
72+
73+
# Manual installation - v2 branch
74+
git clone -b master https://github.com/go-nv/goenv.git ~/.goenv
75+
```
76+
77+
**Migration:** v3 is fully backward compatible with v2. Most users can migrate immediately without changes. See our [migration guide](./docs/MIGRATION.md) for details.
78+
79+
**End of Support Date:** v2 support will be discontinued on or before **December 31, 2028**.
80+
81+
---
82+
3683
### Hints
3784

3885
#### AWS CodeBuild

‎docs/MIGRATION.md‎

Lines changed: 164 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,164 @@
1+
# Migration Guide: goenv v2 to v3
2+
3+
## Overview
4+
5+
goenv v3 is fully backward compatible with v2. Most users can migrate immediately without any changes to their workflows or scripts.
6+
7+
## Key Changes
8+
9+
### Architecture
10+
- **v2**: Shell script-based implementation
11+
- **v3**: Go-based CLI for improved performance and reliability
12+
13+
### Compatibility
14+
✅ All v2 commands work identically in v3
15+
✅ `.go-version` files are fully compatible
16+
✅ Environment variables (`GOENV_ROOT`, `GOPATH`, `GOROOT`) work the same
17+
✅ Plugin system remains compatible
18+
✅ Shell initialization (`goenv init`) unchanged
19+
20+
## Migration Steps
21+
22+
### For Individual Users
23+
24+
1. **If using Homebrew:**
25+
```bash
26+
# Upgrade to v3
27+
brew upgrade goenv
28+
29+
# Verify installation
30+
goenv --version
31+
```
32+
33+
2. **If using Git installation:**
34+
```bash
35+
cd ~/.goenv
36+
git fetch --all
37+
git checkout v3
38+
39+
# Restart your shell
40+
exec $SHELL
41+
42+
# Verify installation
43+
goenv --version
44+
```
45+
46+
3. **Test your setup:**
47+
```bash
48+
# Check current version
49+
goenv version
50+
51+
# List installed versions
52+
goenv versions
53+
54+
# Install a new version (if needed)
55+
goenv install 1.21.0
56+
```
57+
58+
### For CI/CD Systems
59+
60+
#### AWS CodeBuild
61+
62+
Update your `buildspec.yml`:
63+
64+
```yaml
65+
phases:
66+
pre_build:
67+
commands:
68+
- echo "Installing goenv v3..."
69+
- git clone https://github.com/go-nv/goenv.git ~/.goenv
70+
- export GOENV_ROOT="$HOME/.goenv"
71+
- export PATH="$GOENV_ROOT/bin:$PATH"
72+
- eval "$(goenv init -)"
73+
- goenv install 1.21.0
74+
- goenv global 1.21.0
75+
- go version
76+
```
77+
78+
#### Docker Containers
79+
80+
Update your Dockerfile:
81+
82+
```dockerfile
83+
# Install goenv v3
84+
RUN git clone https://github.com/go-nv/goenv.git /root/.goenv
85+
ENV GOENV_ROOT=/root/.goenv
86+
ENV PATH=$GOENV_ROOT/bin:$PATH
87+
88+
# Initialize goenv
89+
RUN echo 'eval "$(goenv init -)"' >> /root/.bashrc
90+
RUN bash -c 'eval "$(goenv init -)" && goenv install 1.21.0 && goenv global 1.21.0'
91+
```
92+
93+
#### GitHub Actions
94+
95+
```yaml
96+
- name: Setup goenv
97+
run: |
98+
git clone https://github.com/go-nv/goenv.git ~/.goenv
99+
echo "GOENV_ROOT=$HOME/.goenv" >> $GITHUB_ENV
100+
echo "$HOME/.goenv/bin" >> $GITHUB_PATH
101+
102+
- name: Install Go via goenv
103+
run: |
104+
eval "$(goenv init -)"
105+
goenv install 1.21.0
106+
goenv global 1.21.0
107+
```
108+
109+
## Staying on v2
110+
111+
If you need to remain on v2 for validation purposes:
112+
113+
### Homebrew
114+
```bash
115+
brew install goenv@2 && brew link goenv@2
116+
```
117+
118+
### Git
119+
```bash
120+
cd ~/.goenv
121+
git checkout master # v2 is maintained on master branch
122+
```
123+
124+
## Rollback to v2
125+
126+
If you encounter issues with v3:
127+
128+
### Homebrew
129+
```bash
130+
brew unlink goenv # keeps install, but allows for switching
131+
brew install goenv@2 && brew link goenv@2
132+
```
133+
134+
### Git
135+
```bash
136+
cd ~/.goenv
137+
git checkout master
138+
exec $SHELL
139+
```
140+
141+
## Support
142+
143+
- **v3 Issues**: [GitHub Issues](https://github.com/go-nv/goenv/issues)
144+
- **v2 Support**: Maintained until April 2028 or End of Support
145+
- **Questions**: [GitHub Discussions](https://github.com/go-nv/goenv/discussions)
146+
147+
## Breaking Changes
148+
149+
There are **no breaking changes** between v2 and v3. All commands, flags, and behaviors remain consistent.
150+
151+
## Performance Improvements
152+
153+
v3 offers significant performance improvements over v2:
154+
- Faster command execution (Go vs shell scripts)
155+
- Reduced startup time
156+
- More efficient version switching
157+
- Improved error handling and messaging
158+
159+
## Recommended Migration Timeline
160+
161+
- **Immediate**: Individual developer machines
162+
- **1-2 weeks**: Development and staging environments
163+
- **1-2 months**: Production CI/CD pipelines (after validation)
164+
- **2-6 months**: Critical infrastructure with strict change control

0 commit comments

Comments
 (0)