docs: add docs to guard against some pitfalls

Adds warnings about Rosetta and running old versions of bash.

docs/developer-setup.md

@@ -61,13 +61,29 @@ xcode-select --install
 brew install openssl readline sqlite3 xz zlib bash
 ```
-**NOTE for macOS Users**: in the previous command we also installed a modern version of `bash`.
+### Step 2.1: Macos Only: you're gonna need a better shell
+
+In the previous command we also installed a modern version of `bash`.
 This is because macOS ships with an very outdated version (circa 2007) of `bash`, due to licensing issues.
 Homebrew should install a modern version (at least v5).
-If scripts are failing on macOS, check that the Homebrew copy of bash is on the path, eg: `/opt/homebrew/bin/bash`.
+
+Alongside _installing_ a modern `bash`,
+you'll also need to make sure that you're _using_ a modern `bash` as your login shell.
+Configure your terminal to use the homebrew install (likely `/opt/homebrew/bin/bash`) for new sessions,
+instead of the default, `/bin/bash`. If you run bash, you can check the version with `echo $BASH_VERSION`,
+and making sure it's at least v5.
+
+You can also configure your default macos login shell to use the newer version of `bash`, by changing your shell, as follows:
+
+1. `sudo vi /etc/shells` and add a line for `/opt/homebrew/bin/bash` (or wherever your `bash` resides) to the end of the file.
+2. `chsh -s /opt/homebrew/bin/bash` to configure your login to use the new bash.
+
+Alternatively, use a different shell, eg `chsh -s /bin/zsh`.
 ### Step 2.5: Apple Silicon users only: install Rosetta
+**Note**: this step is under review: please confirm whether this is still required in <https://gitlab.com/gitlab-com/gl-infra/gitlab-dedicated/team/-/issues/5272> before proceeding.
+
 > To determine if you are using an Apple with Silicon or an Intel-based processor, select the **Apple** menu icon in the top-left of the desktop and click **About This Mac**. On Mac computers with Apple silicon, About This Mac shows an item labeled **Chip**, followed by the name of the chip (ex. **Chip** Apple M1 Pro). On Mac computers with an Intel processor, About This Mac shows an item labeled **Processor**, followed by the name of an Intel processor.
 If you are running Apple Silicon it's highly recommended that you install Rosetta. Many downstream tools still generate `amd64` binaries only, and even if the tools support `arm64`, `asdf` plugins also need to support it, which they may not yet.
@@ -257,3 +273,11 @@ mise checkov@2.5.8                 ✓ installed
 **Note**: `mise` (formerly known as `rtx`). If you haven't [migrated yet](https://gitlab.com/gitlab-com/runbooks/-/issues/134), replace `mise` with `rtx` in the above commands.
 Additionally, please consider opening an issue in the appropriate tracker, so that a better long-term solution can be applied.
+
+## Macos running in Rosetta Emulation Mode
+
+If your shell or terminal application is running in Rosetta Emulation Mode, you're going to have a bad time.
+Make sure that you're using a Universal or Apple Silicon terminal program.
+
+You can check if you're running Intel emulation on your shell and terminal using the Activity Monitor,
+by reviewing the `Kind` column.