chore: apply copier template

This updates the developer documentation for initial setup to recommend
using rtx over asdf.

See https://gitlab.com/gitlab-com/runbooks/-/issues/134 for more details.

docs/developer-setup.md

@@ -22,7 +22,7 @@ Once 1password-cli is installed you can verify the installation using:
 op --version
 ```
-Note that v2 of the 1password-cli is required.
+**Note: v2 of the 1password-cli is required.**
 ### Step 2: Setup Development Libraries
@@ -61,32 +61,52 @@ If it is not running, it is likely that it is not installed, so continue with th
 softwareupdate --install-rosetta --agree-to-license
 ```
-### Step 3: Install `asdf`
-Installation instructions for `asdf` can be found at <https://asdf-vm.com/guide/getting-started.html#_1-install-dependencies>.
-If you're running on macos, the recommended approach is to use Homebrew:
-```shell
-brew install asdf
+### Step 3.1: Uninstall `asdf` before installing `rtx`
+The Infrastructure department is currently migrating from `asdf` to `rtx`. See [gitlab-com/runbooks#134](https://gitlab.com/gitlab-com/runbooks/-/issues/134) for details of the migration. Many projects now support both `rtx` and `asdf`, but if you're experiencing errors running `scripts/install-asdf-plugins.sh` on a project, please leave a comment on [gitlab-com/runbooks#134](https://gitlab.com/gitlab-com/runbooks/-/issues/134).
+**It is not recommended that you run `asdf` alongside `rtx`.**
+Please ensure that you uninstall `asdf` before installing `rtx`.
+
+To uninstall `asdf`, full instructions are available at <https://asdf-vm.com/manage/core.html#uninstall>.
+
+For MacOS users who installed `asdf` with Homebrew, remove any includes of `asdf` from your Shell initialization, then use Homebrew to remove `asdf`:
+
+```console
+$ # find asdf references in your shell rc files
+$ grep -Er 'asdf.(ba)?sh' ~/.bash_profile ~/.bashrc ~/.zshrc ~/.oh-my-zsh/custom/*
+$ # edit the files to delete any references
+$ vi ...
+$ # now, uninstall asdf
+$ brew uninstall asdf --force
+$ # open a new terminal before continuing...
 ```
-Linux users should follow the instructions for their package manager in [the ASDF documentation](https://asdf-vm.com/guide/getting-started).
-#### Step 3.5: Hook `asdf` into your shell
-Once you've installed `asdf`, add the following line to your shell. Remember to restart your terminal for the change to take affect.
-### Macos with Homebrew
+### Step 3.2: Install `rtx`
+[`rtx`](https://github.com/jdx/rtx) is a polyglot runtime manager. It is compatible with [`asdf`](https://asdf-vm.com/) and relies on the `asdf` plugin ecosystem, but has some advantages over `asdf` in that it generally requires fewer shims and is faster.
+If you're running on MacOS, the recommended approach is to use Homebrew:
 ```shell
-. $(brew --prefix asdf)/asdf.sh
+brew install rtx
 ```
-### Linux
+Linux users should follow the instructions for their package manager in [the rtx documentation](https://github.com/jdx/rtx#apt).
+
+#### Step 3.3: Hook `rtx` into your shell
+
+Once you've installed `rtx`, add the following line to your shell. Remember to restart your terminal for the change to take affect.
 ```shell
-. <path to asdf install>/asdf.sh
+# bash
+echo 'eval "$('$(which rtx)' activate bash)"' >> ~/.bashrc
+# zsh
+echo 'eval "$('$(which rtx)' activate zsh)"' >> ~/.zshrc
+# fish
+echo 'rtx activate fish | source' >> ~/.config/fish/config.fish
 ```
 Did you remember to restart your terminal? Good.
@@ -99,7 +119,7 @@ Install all the plugins by running:
 ./scripts/install-asdf-plugins.sh
 ```
-This will install required `asdf` plugins, and install the correct versions of the development tools.
+This will install required `asdf`/`rtx` plugins, and install the correct versions of the development tools.
 Note that after pulling changes to the repository, you may sometimes need to re-run `./scripts/install-asdf-plugins.sh` to update your locally installed plugins and tool-versions.
@@ -107,43 +127,43 @@ Note that after pulling changes to the repository, you may sometimes need to re-
 We use CI checks to ensure that tool versions used in GitLab-CI and on developer instances don't go out of sync.
-### Keeping Versions in Sync between GitLab-CI and `asdf`.
-`asdf` (and `.tool-versions` generally) is the SSOT for tool versions used in this repository.
+### Keeping Versions in Sync between GitLab-CI and `.tool-versions`.
+The `.tool-versions` file is the SSOT for tool versions used in this repository.
 To keep `.tool-versions` in sync with `.gitlab-ci.yml`, there is a helper script,
-`./scripts/update-asdf-version-variables`.
+`./scripts/update-asdf-version-variables.sh`.
 #### Process for updating a Tool Version
 ```shell
-./scripts/update-asdf-version-variables
+./scripts/update-asdf-version-variables.sh
 ```
 1. Update the version in `.tool-versions`
-1. Run `asdf install` to install latest version
-1. Run `./scripts/update-asdf-version-variables` to update a refresh of the `.gitlab-ci-asdf-versions.yml` file
+1. Run `rtx install` to install latest version
+1. Run `./scripts/update-asdf-version-variables.sh` to update a refresh of the `.gitlab-ci-asdf-versions.yml` file
 1. Commit the changes
 1. A CI job (see [`asdf-tool-versions.md`](../asdf-tool-versions.md)) will validate the changes.
-# Diagnosing `asdf` setup issues
-## `asdf` plugins don't return versions as expected
-To avoid installing dependencies, `asdf` plugins often rely on basic Unix text processing utilities like `grep`, `sed` and `awk` to parse JSON. Many rely on the fact that responses from the GitHub API are pretty-printed JSON, not minimised (or machine parsable) JSON. However, the GitHub API will only pretty-print JSON when it detects the User-Agent request header as being `curl`. For other user agents, the response will be minimised for efficiency.
+# Diagnosing `rtx` setup issues
+## `asdf`/`rtx` plugins don't return versions as expected
+To avoid installing dependencies, `asdf`/`rtx` plugins often rely on basic Unix text processing utilities like `grep`, `sed` and `awk` to parse JSON. Many rely on the fact that responses from the GitHub API are pretty-printed JSON, not minimised (or machine parsable) JSON. However, the GitHub API will only pretty-print JSON when it detects the User-Agent request header as being `curl`. For other user agents, the response will be minimised for efficiency.
 Ensure that you haven't overridden your `curl` user-agent on your workstation.
-Check your `.curlrc` for the `user-agent` setting. Additionally, running `curl https://api.github.com/orgs/gitlabhq` should return pretty-printed JSON. If the response contains minimised JSON, many `asdf` plugins may not work as expected.
-## Plugins require other asdf tools
+Check your `.curlrc` for the `user-agent` setting. Additionally, running `curl https://api.github.com/orgs/gitlabhq` should return pretty-printed JSON. If the response contains minimised JSON, many `asdf`/`rtx` plugins may not work as expected.
+## `asdf`/`rtx` plugins require other `asdf`/`rtx` plugins
 If you find that a plugin is failing to install, it sometimes helps to setup a global default. Care has been taken to avoid this situation, but if you're stuck, give it a try:
 ```shell
 # If a plugin is complaining that it cannot compile because golang hasn't been configured...
 # set the global version of golang the same as the current version
-asdf global golang $(asdf current golang|awk '{ print $2 }')
-asdf install
+rtx global golang $(rtx current golang)
+rtx install
 ```
 If this happens, please open an issue in the appropriate tracker, so that a better long-term solution can be applied.