From 53cd4544741cab2e58ca7ea8aa36c9c28890b0a1 Mon Sep 17 00:00:00 2001 From: Trevor Brown Date: Tue, 29 Oct 2024 09:29:00 -0400 Subject: [PATCH] feat(golang-rewrite): create version 0.14 to 0.15 upgrade guide --- docs/guide/upgrading-from-v0-14-to-v0-15.md | 108 ++++++++++++++++++++ 1 file changed, 108 insertions(+) create mode 100644 docs/guide/upgrading-from-v0-14-to-v0-15.md diff --git a/docs/guide/upgrading-from-v0-14-to-v0-15.md b/docs/guide/upgrading-from-v0-14-to-v0-15.md new file mode 100644 index 00000000..7a3140f9 --- /dev/null +++ b/docs/guide/upgrading-from-v0-14-to-v0-15.md @@ -0,0 +1,108 @@ +# Upgrading From Version 0.14.x to 0.15.0 + +asdf versions 0.14.1 and older were written in Bash and distributed as a set of +Bash scripts with the `asdf` function loaded into your shell. asdf version +0.15.0 is a complete rewrite of asdf in Go. Since it is a complete rewrite +there are a number of breaking changes and it is now distributed as a binary +rather than a set of scripts. + +## Breaking Changes + +### Hyphenated commands have been removed + +asdf version 0.14.1 and earlier supported by hyphenated and non-hyphenated +versions of certain commands. With version 0.15.0 only the non-hyphenated +versions are supported. The affected commands: + +* `asdf list-all` -> `asdf list all` +* `asdf plugin-add` -> `asdf plugin add` +* `asdf plugin-list` -> `asdf plugin list` +* `asdf plugin-list-all` -> `asdf plugin list all` +* `asdf plugin-update` -> `asdf plugin update` +* `asdf plugin-remove` -> `asdf plugin remove` + +### `asdf global` and `asdf local` commands have been replaced by the `asdf set` command + +`asdf global` and `asdf local` have been replaced by `asdf set`, which aims to +provide the same functionality while using terminology that is less likely to +mislead the user. TODO: Add more details here + +### `asdf update` command has been removed + +Updates can no longer be performed this way. Use your OS package manager or +download the latest binary manually. Additionally, the `asdf update` command +present in versions 0.14.1 and older cannot upgrade to version 0.15.0 because +the install process has changed. **You cannot upgrade to the latest Go +implementation using `asdf update`.** + +### `asdf shell` command has been removed + +This command actually set an environment variable in the user's current shell +session. It was able to do this because `asdf` was actually a shell function, +not an executable. The new rewrite removes all shell code from asdf, and it is +now a binary rather than a shell function, so setting environment variables +directly in the shell is no longer possible. + +## Installation + +Installation of version 0.15.0 is much simpler than previous versions of asdf. It's just three steps: + +* Download the appropriate `asdf` binary for your operating system/architecture combo and place it in a directory on your `$PATH` +* Set `ASDF_DATA_DIR` to the directory you'd like asdf to install plugins, versions, and shims. +* Add `$ASDF_DATA_DIR/shims` to the front of your `$PATH. + +If your operating system's package manager already offers asdf 0.15.0 that is +probably the best method for installing it. Upgrading asdf is now only possible +via OS package managers and manual installation. There is no self-upgrade +feature. + +### Upgrading Without Losing Data + +You can upgrade to the latest version of asdf without losing your existing +install data. It's the same sequence of steps as above. + +#### 1. Download the appropriate `asdf` binary for your operating system & architecture + +Download the binary and place it in a directory on your path. I chose to place +the asdf binary in `$HOME/bin` and then added `$HOME/bin` to the front of my +`$PATH`: + +``` +# In .zshrc, .bashrc, etc... +export PATH="$HOME/bin:$PATH"` +``` + +#### 2. Set `ASDF_DATA_DIR` + +Run `asdf info` and copy the line containing the `ASDF_DATA_DIR` variable: + +``` +... +ASDF_DATA_DIR="/home/myuser/.asdf" +... +``` + +In your shell RC file (`.zshrc` if Zsh, `.bashrc` if Bash, etc...) add a line +to the end setting `ASDF_DATA_DIR` to that same value: + +```bash +export ASDF_DATA_DIR="/home/myuser/.asdf" +``` + +#### 3. Add `$ASDF_DATA_DIR/shims` to the front of your `$PATH + +In your shell RC file (same file as step #2) add `$ASDF_DATA_DIR/shims` to the +front of your path: + +```bash +export ASDF_DATA_DIR="/home/myuser/.asdf" +export PATH="$ASDF_DATA_DIR/shims:$PATH" +``` + +### Testing + +If you aren't sure if the upgrade to 0.15.0 will break things for you can you +can test by installing 0.15.0 in addition to your existing version as described +above in "Upgrading Without Losing Data". If it turns out that the upgrade to +0.15.0 breaks things for you simply remove the lines you added to your shell +RC file.