Start using Yarn to manage JavaScript dependencies (#1824)

* Start using `yarn` for vendor assets

Until this commit, Gollum has included JavaScript assets by committing
the source code to the `lib/gollum/public/gollum/javascript/` directory
and including them for compilation in the Sprockets asset manifest file
at `lib/gollum/public/gollum/javascript/app.js`. This has been a
reasonable way to deal with third-party JavaScript, but there are a few
downsides:

  - It's a burden to find out if JavaScript dependencies have been
    updated and require updating in Gollum.
  - It doesn't give us good visibility into the JavaScript dependencies
    required by our dependencies.
  - It forces us to commit external code to our repository, which can
    make our developer tools more difficult to configure or use. For
    example: when I search for key words in the repository using
    Ripgrep, I often get "garbage" results from minified JavaScript.

Managing JavaScript dependencies via a JS package manager can resolve
all of these issues.

This commit allows us to manage JavaScript dependencies using the Yarn
package manager for Node JS modules[1]. I chose Yarn over NPM for one
reason: Yarn is the JavaScript package manager that Rails uses by
default. So many Ruby developers will already be familiar with Yarn.

To demonstrate how this can change how we manage JS assets in Gollum,
I've configured Yarn and started to manage the `mousetrap` dependency
with it. I chose `mousetrap` to start because it's a smaller, mostly
uncomplicated dependency. I was easily able to manually test that
`mousetrap` is still working after re-compiling the assets.

Hopefully this gives anyone reading enough context to jump in and start
moving our third-party JS assets out of the codebase.

[1]: https://yarnpkg.com/

* Recompile assets

* Add dev environment setup info to CONTRIBUTING

Now that we require additional tooling to manage JavaScript
dependencies, it seemed reasonable to add more documentation around
setting up one's development environment.

* Don't compile assets without `yarn`-managed ones

If a developer compiled assets without first running `yarn install`, we
would get incomplete collection of up-to-date assets.

Let's ensure that the developer has all the required assets by enforcing
this in the precompile task they should be using to compile production
assets to begin with.

Rakefile

@@ -190,10 +190,10 @@ task :changelog do
       exit!
     end
   end
-  
+
   latest_changes = File.open(latest_changes_file)
   version_pattern = "# #{version}"
-  
+
   if !`grep "#{version_pattern}" #{history_file}`.empty?
     puts "#{version} is already described in #{history_file}"
     exit!
@@ -208,13 +208,13 @@ task :changelog do
     puts "#{latest_changes_file} is empty!"
     exit!
   end
-  
+
   body = latest_changes.read
   body.scan(/\s*#\s+\d\.\d.*/) do |match|
     puts "#{latest_changes_file} may not contain multiple markdown headers!"
     exit!
   end
-  
+
   temp = Tempfile.new
   temp.puts("#{version_pattern} / #{date}\n#{body}\n")
   temp.close
@@ -224,11 +224,29 @@ end
 
 desc 'Precompile assets'
 task :precompile do
+  # Attempt to install JavaScript dependencies managed by Yarn via the
+  # `package.json` file in Gollum's project root. If it fails, raise an error
+  # and exit the task early.
+  puts "\n  Installing `yarn`-managed JavaScript dependencies...  \n\n"
+  system "yarn install"
+    unless $?.success?
+    raise "This task tried to run `yarn install` to get up-to-date "          \
+      "JavaScript dependencies before precompilation. But it failed. Please " \
+      "run `yarn install` manually from your shell and resolve any issues. "  \
+      "It's possible that you just need to install `yarn` on your system."
+  end
+
   require './lib/gollum/app.rb'
+
+  # Next, configure the Sprockets asset pipeline and precompile production-
+  # ready assets.
   Precious::App.set(:environment, :production)
+
   env = Precious::Assets.sprockets
-  path = ENV.fetch('GOLLUM_ASSETS_PATH', ::File.join(File.dirname(__FILE__), 'lib/gollum/public/assets'))
+  path = ENV.fetch 'GOLLUM_ASSETS_PATH',
+    File.join(File.dirname(__FILE__), 'lib/gollum/public/assets')
   manifest = Sprockets::Manifest.new(env, path)
+
   Sprockets::Helpers.configure do |config|
     config.environment = env
     config.prefix      = Precious::Assets::ASSET_URL
@@ -236,6 +254,7 @@ task :precompile do
     config.public_path = path
     config.manifest    = manifest
   end
-  puts "Precompiling assets to #{path}..."
+
+  puts "\n  Precompiling assets to #{path}...  \n\n"
   manifest.compile(Precious::Assets::MANIFEST)
 end