Switch to asdf as preferred dependency manager

3 files changed, 79 insertions, 42 deletions

diff --git a/.tool-versions b/.tool-versions
new file mode 100644
index 00000000..1e92e394
--- /dev/null
+++ b/.tool-versions
@@ -0,0 +1,3 @@
+ruby 2.6.6
+nodejs 12.18.3
+yarn 1.22.4
diff --git a/README.md b/README.md
index aad41533..efa960de 100644
--- a/README.md
+++ b/README.md
@@ -42,7 +42,7 @@ here's what you will need to have:
 
 - Environment: Unix/Linux or macOS.
 - Ruby 2.6.6.
-- Node (latest LTS).
+- Node.js (latest LTS).
 - Yarn (latest version).
 - Xcode *(macOS only)*:
   - Run `xcode-select --install` to install the command line tools only.
@@ -52,12 +52,28 @@ here's what you will need to have:
 On Windows, the process described here would be different, but as most of
 contributors use Unix, we'll go over this process for macOS and Linux users.
 
-### Ruby
+## Install dependencies
 
-The recommended way is to use a Ruby version manager to install Ruby in your
-system.
+There are a couple of options for installing dependencies for `gitlab-docs`:
 
-We recommend [rbenv](https://github.com/rbenv/rbenv):
+- Using [separate dependency managers](#use-separate-dependency-managers) for Ruby, Node.js, and
+  Yarn.
+- The [unified dependency manager](#use-asdf) `asdf` for Ruby, Node.js, and Yarn.
+
+The choice of which to use will depend on what you currently use. If you don't yet have Ruby,
+Node.js, and Yarn set up, use [`asdf`](https://asdf-vm.com/#/).
+
+### Use separate dependency managers
+
+In the instructions below, you:
+
+- Install Ruby using `rbenv`.
+- Install Node.js using `nvm`.
+- Install Yarn using your preferred method in their installation instructions.
+
+#### Ruby
+
+To install Ruby using [rbenv](https://github.com/rbenv/rbenv):
 
 1. [Install rbenv](https://github.com/rbenv/rbenv#installation).
 1. Install the latest Ruby:
@@ -77,38 +93,70 @@ Check your:
 - Ruby version with `ruby --version`.
 - Bundler version with `bundle --version`. You need version 1.17.3.
 
-### Node
-
-The recommended way is to use a Node version manager to install Node in your
-system.
+#### Node.js
 
-We recommend NVM:
+To install Node.js using [nvm](https://github.com/nvm-sh/nvm):
 
-1. [Install NVM](https://github.com/nvm-sh/nvm#installation-and-update).
-1. Install the latest Node:
+1. [Install nvm](https://github.com/nvm-sh/nvm#installation-and-update).
+1. Install the latest Node.js:
 
    ```shell
    nvm install --lts
    ```
 
-1. Use the newly installed Node:
+1. Use the newly installed Node.js:
 
    ```shell
    nvm use --lts --default
    ```
 
-Check your Node version with `node -v`.
+Check your Node.js version with `node -v`.
 
-### Yarn
+#### Yarn
 
 Install [yarn](https://yarnpkg.com/en/docs/install), a package manager for the
-Node ecosystem.
+Node.js ecosystem.
 
 Check your Yarn version with `yarn -v`.
 
+### Use `asdf`
+
+To install Ruby, Node.js, and Yarn using `asdf`:
+
+1. [Install `asdf`](https://asdf-vm.com/#/core-manage-asdf-vm?id=install).
+1. Add the Ruby, Node.js, and Yarn [`asdf` plugins](https://asdf-vm.com/#/core-manage-plugins)
+   required to install versions of these dependencies:
+
+   ```shell
+   asdf plugin add ruby
+   asdf plugin add nodejs
+   asdf plugin add yarn
+   ```
+
+1. [Install](https://asdf-vm.com/#/core-manage-versions) the dependencies listed in the project's
+   `.tool-versions` file:
+
+   ```shell
+   asdf install
+   ```
+
+1. Set the installed versions of Ruby, Node.js, and Yarn to be global for projects that don't use
+   `.tool-versions` files. For example to set Ruby 2.6.6 as the global default, run:
+
+   ```shell
+   asdf global ruby 2.6.6
+   ```
+
+Check your:
+
+- Ruby version with `ruby --version`.
+- Bundler version with `bundle --version`. You need version 1.17.3.
+- Node.js version with `node -v`.
+- Yarn version with `yarn -v`
+
 ## Install Nanoc's dependencies
 
-The project depends on many Ruby and Node libraries. To install these:
+The project depends on many Ruby and Node.js libraries. To install these:
 
 1. Open a terminal and navigate to your local checkout of this project.
 1. Run:
diff --git a/commands/frontend.rb b/commands/frontend.rb
index 9c145dee..24d64d4b 100644
--- a/commands/frontend.rb
+++ b/commands/frontend.rb
@@ -8,33 +8,19 @@ flag   :h, :help, 'show help for this command' do |value, cmd|
   exit 0
 end
 run do |opts, args, cmd|
+  puts 'Compiling JavaScript...'
+  unless system('yarn install --frozen-lockfile')
+    abort <<~ERROR
+      Error: failed to run yarn. JavaScript compilation failed. For more information, see:
+      https://gitlab.com/gitlab-org/gitlab-docs/blob/master/README.md
 
-  puts '--------------------------------'
-
-  if check_requirements?
-    puts 'Compiling JavaScript...'
-
-    system('yarn install --frozen-lockfile')
-
-    system('yarn bundle')
+      ERROR
   end
-end
+  unless system('yarn bundle')
+    abort <<~ERROR
+      Error: failed to run yarn. JavaScript compilation failed. For more information, see:
+      https://gitlab.com/gitlab-org/gitlab-docs/blob/master/README.md
 
-def check_requirements?
-  puts 'Checking requirements...'
-
-  has_requirements = command_exists?('node') && command_exists?('yarn')
-
-  unless has_requirements
-    puts 'Your system may be missing some requirements.'
-    puts 'Please refer to the installation instructions for more details:'
-    puts 'https://gitlab.com/gitlab-org/gitlab-docs/blob/master/README.md'
+      ERROR
   end
-  has_requirements
-end
-
-def command_exists?(command)
-  exists = system("which #{command} > /dev/null 2>&1")
-  puts "🚨 #{command} is not installed!" unless exists
-  exists
 end