Improve docs on migration for Homebrew installs

[rdonkin]

I made a few notes on what worked for me to upgrade/migrate from rtx to mise on macOS 12.x Monterey with Homebrew 4.2.2.

It would be great to include something like this as it wasn't that easy to figure out for a non-expert in brew.

Homebrew upgrade notes

To upgrade to mise from rtx installed using Homebrew.

The jdxcode Homebrew tap is no longer used for mise, but the commands below will work whether you installed rtx from that tap or not:

brew update
brew migrate --force rtx
brew upgrade mise   # Ensures you are on latest mise version, not an rtx version renamed to mise

# Cleaning up - if you used this
brew untap jdxcode/tap    

General migration tips

Summary of auto migration done by mise:

• This moves and migrates the main config file to ~/.config/mise/config.toml
• It also copies and migrates all plugin installs to ~/.local/share/mise (leaving the ~/.local/share/rtx` dir unchanged)

Manual migration steps you may need to do:

• change any rtx environment variables from RTX_ to MISE_
• if your ~.config/mise/config.toml file includes a [settings] section, the contents should be moved into the new ~.config/mise/settings.toml file, to remove a deprecation warning. Don't include the [settings] section header.

Minor tips:

• edit any shell aliases or functions to use new paths
• use unset rtx in all terminal tabs to remove the old rtx shell function - or just restart your terminal app

GitHub Actions migration

When ready, you can upgrade rtx-action@v1 to mise-action@v2 - this isn't urgent since rtx-action@v1 still works for now.

[rdonkin]

Added some general migration tips above.

[jdx]

thanks for this @rdonkin, it's really useful but I worry people may not discover it here. Would you mind literally just copying this over to https://github.com/jdx/mise-docs/blob/main/docs/rtx.md ? If not I may see if I can get around to it but I've also got a number of recent bugs I should focus on

[jdx]

if your ~.config/mise/config.toml file includes a [settings] section, the contents should be moved into the new ~.config/mise/settings.toml file, to remove a deprecation warning. Don't include the [settings] section header.

I'm going to try to get a patch out for mise to fail parsing if it includes this header (or includes anything extra) so at least if people get it wrong it will fail more obviously

[rdonkin]

Sounds good @jdx, I will do a PR for docs, hopefully in a few days or so.

I think it would help to add some sub-headings to existing page's content, including headings above and some new ones like 'why rename' and 'feedback'.

[jdx]

I would very much appreciate that, these are excellent tips formatted very nicely

[jdx]

going to close since I assume most people have migrated over by now