Skip to content
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.

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

Jump to bottom

x/website: highlight removal of previous Go install in Linux installation instructions #44426

Closed
dmitshur opened this issue Feb 19, 2021 · 3 comments
Closed

x/website: highlight removal of previous Go install in Linux installation instructions #44426

dmitshur opened this issue Feb 19, 2021 · 3 comments
Labels
Documentation FrozenDueToAge NeedsFix The path to resolution is known, but the work has not been done.
Projects
Go Release Team
Milestone
Unreleased

Comments

@dmitshur
Copy link
Contributor

Experience and feedback in #44320 (thank you @jpmieville, @davecheney, @agnivade) suggests that the current Linux installation instructions are prone to a user mistake: missing the step of removing the previous Go installation at /usr/local/go before extracting the new Go version into the same location.

Making that mistake results in a corrupted Go installation which may produce strange errors. Worse yet, there is a possibility of it failing silently but producing incorrect results, compromising the reliability of the installed Go version.

There is a mention that the previous Go installation should be removed above the numbered steps:

image

This issue is about highlighting it to reduce the chances of this important step being overlooked by users.

CC @straut, @jayconrod, @golang/release.
@dmitshur dmitshur added Documentation NeedsInvestigation Someone must examine and confirm this is a valid issue and not a duplicate of an existing one. labels Feb 19, 2021
@dmitshur dmitshur added this to the Unreleased milestone Feb 19, 2021
@dmitshur
Copy link
Contributor Author

dmitshur commented Feb 19, 2021 •
edited

Given how important the step of removing the previous /usr/local/go directory before extracting, I think we must include it in the numbered steps.

The current instructions link to https://golang.org/doc/manage-install#uninstalling, but that's less ideal for two reasons: 1) we only need the /usr/local/go directory to be removed, while Uninstalling Go involves removing Go bin directory from PATH, which doesn't need to be done, and 2) it links to another page, taking the reader out of context; it's better to keep the installation instructions contained on a single page.

Step 1 also repeats "Download the archive" unnecessary: that was done in the https://golang.org/doc/install#download step above.

I came up with two alternatives that might work better.

Alternative A

The first one avoids including the "rm -rf" command, asking the user to take it on themselves to know how to remove a directory on Linux.

It also adds the -k parameter to the tar command, so that the tar command fails if a previous tree hasn't been removed. This is better than silently proceeding and getting a corrupted installation.

image

Alternative B

The second one combines "rm -rf /usr/local/go" with the "tar" command, and includes an Important note about what will happen and that the user should backup data as needed. Hopefully this is safe and convenient. It's unfortunate that the command is either long or split across two lines though.

image

I'm currently slightly leaning towards B, because it seems more convenient, reliable, and safe. But if there are concerns with suggesting "rm -rf" then A should be the next best thing.

Let me know if you have thoughts or ideas for how to improve this.

@dmitshur dmitshur mentioned this issue Feb 19, 2021
Closed
@dmitshur dmitshur added this to In Progress in Go Release Team Feb 19, 2021
@dmitshur dmitshur added NeedsDecision Feedback is required from experts, contributors, and/or the community before a change can be made. and removed NeedsInvestigation Someone must examine and confirm this is a valid issue and not a duplicate of an existing one. labels Feb 19, 2021
@jayconrod
Copy link
Contributor

Alternative B seems better to me. I think it's better to be clear that the old tree is removed while having something pasteable.

@dmitshur dmitshur added NeedsFix The path to resolution is known, but the work has not been done. and removed NeedsDecision Feedback is required from experts, contributors, and/or the community before a change can be made. labels Feb 19, 2021
@gopherbot
Copy link

Change https://golang.org/cl/294369 mentions this issue: _content/doc: highlight 'remove old Go tree' step before extracting

Go Release Team automation moved this from In Progress to Done Feb 25, 2021
@golang golang locked and limited conversation to collaborators Feb 25, 2022
passionSeven added a commit to passionSeven/website that referenced this issue Oct 18, 2022
@passionSeven
_content/doc: highlight 'remove old Go tree' step before extracting
4d88c41 
Fixes golang/go#44426.

Change-Id: Ie7eb15c239e522d28412a4d8fe2db37bab55f4a4
Reviewed-on: https://go-review.googlesource.com/c/website/+/294369
Trust: Dmitri Shuralyov <dmitshur@golang.org>
Run-TryBot: Dmitri Shuralyov <dmitshur@golang.org>
TryBot-Result: Go Bot <gobot@golang.org>
Reviewed-by: Jay Conrod <jayconrod@google.com>
Sign up for free to subscribe to this conversation on GitHub. Already have an account? Sign in.
Assignees
No one assigned
Labels
Documentation FrozenDueToAge NeedsFix The path to resolution is known, but the work has not been done.
Projects
Go Release
Archived in project
Go Release Team
Done
Milestone
Unreleased
Development

No branches or pull requests
3 participants
@jayconrod @dmitshur @gopherbot