Merge branch 'doc-asdf-fixes' into 'main'

doc: add documentation for some potential asdf pitfalls

See merge request gitlab-com/gl-infra/common-ci-tasks!140

docs/developer-setup.md

@@ -66,3 +66,26 @@ To keep `.tool-versions` in sync with `.gitlab-ci.yml`, there is a helper script
 1. Run `./scripts/update-asdf-version-variables` 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.
+
+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
+
+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
+```
+
+If this happens, please open an issue in the appropriate tracker, so that a better long-term solution can be applied.