Merge branch 'update-docs' into 'main'

chore: update copier template

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

.copier-answers.yml

@@ -3,7 +3,7 @@
 # See the project for instructions on how to update the project
 #
 # Changes here will be overwritten by Copier; NEVER EDIT MANUALLY
-_commit: v1.13.0
+_commit: v1.14.0
 _src_path: https://gitlab.com/gitlab-com/gl-infra/common-template-copier.git
 ee_licensed: false
 golang: false

.copier-version

 # This file is used to track the version of copier uses
-v1.13.0 # datasource=gitlab-releases depName=gitlab-com/gl-infra/common-template-copier
+v1.14.0 # datasource=gitlab-releases depName=gitlab-com/gl-infra/common-template-copier

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.

scripts/install-asdf-plugins.sh

 #!/usr/bin/env bash
+# Vendored from https://gitlab.com/gitlab-com/gl-infra/common-template-copier
+# Consider contributing upstream when updating this file
 # This script will install the ASDF plugins required for this project
@@ -59,8 +61,20 @@ setup_mise() {
   trap 'do_mise_install' EXIT
   do_mise_install() {
-    cat "$temp_MISE_SHORTHANDS_FILE"
-    MISE_SHORTHANDS_FILE=$temp_MISE_SHORTHANDS_FILE $MISE_COMMAND install
+    export MISE_SHORTHANDS_FILE=$temp_MISE_SHORTHANDS_FILE
+    $MISE_COMMAND install || {
+      # mise installs plugins in parallel, so order may lead to breaks when some plugins require others
+      # the best workaround is to use `.mise.toml` with dependencies, but we can't do this until the
+      # migration off asdf, in https://gitlab.com/gitlab-com/runbooks/-/issues/134 is complete.
+      # until then, a retry without parallelism should be sufficient.
+
+      # Export tool paths so that plugins can find dependencies
+      eval "$(mise env --shell bash)"
+
+      echo "$MISE_COMMAND install failed. Attempting a retry as it may be a plugin dependency issue" >&2
+      RTX_JOBS=1 MISE_JOBS=1 $MISE_COMMAND install
+    }
+    unset MISE_SHORTHANDS_FILE
     rm -f "$temp_MISE_SHORTHANDS_FILE"
   }
@@ -91,6 +105,23 @@ setup_mise() {
   }
 }
+# Do some validation to ensure that the environment is not misconfigured, as this may
+# save a bunch of debugging effort down the line.
+
+# Detect Rosetta 2
+if [[ $(uname -m) == "arm64" ]] && [[ $(uname -p) == "x86_64" ]]; then
+  echo "This shell is running in Rosetta emulating x86_64. Please use native mode Apple Silicon." >&2
+  echo "For help visit https://gitlab.com/gitlab-com/gl-infra/common-ci-tasks/-/blob/main/docs/developer-setup.md" >&2
+  exit 1
+fi
+
+# Detect ancient versions of bash
+if ((BASH_VERSINFO[0] < 4)); then
+  echo "You're running bash < v4.0.0. Please upgrade to a newer version." >&2
+  echo "For help visit https://gitlab.com/gitlab-com/gl-infra/common-ci-tasks/-/blob/main/docs/developer-setup.md" >&2
+  exit 1
+fi
+
 if command -v mise >/dev/null; then
   MISE_COMMAND=$(which mise)
   export MISE_COMMAND

scripts/prepare-dev-env.sh

 #!/usr/bin/env bash
+# Vendored from https://gitlab.com/gitlab-com/gl-infra/common-template-copier
+# Consider contributing upstream when updating this file
 set -euo pipefail

scripts/update-asdf-version-variables.sh

 #!/usr/bin/env bash
+# Vendored from https://gitlab.com/gitlab-com/gl-infra/common-template-copier
+# Consider contributing upstream when updating this file
 # See the README.md for details of how this script works