Merge pull request #386 from transcom/bl-adr-use-asdf-for-node

ADR to use asdf for node as well as golang

.github/workflows/deploy.yml

@@ -17,7 +17,7 @@ jobs:
 
       - uses: actions/setup-node@v3
         with:
-          node-version-file: ".node-version"
+          node-version-file: ".tool-versions"
           cache: "yarn"
 
       - name: Install yarn

.node-version

@@ -1 +1,2 @@
-16.15.0
+18.13.0
+

.tool-versions

@@ -0,0 +1 @@
+nodejs 18.13.0

Brewfile.local

@@ -1,2 +1,2 @@
-brew 'nodenv'
+brew 'asdf'
 brew 'yarn'

docs/adrs/0046-use-nodenv.md

@@ -3,6 +3,12 @@ title: 0046 Use nodenv to manage Node versions in development
 ---
 # Use [nodenv](https://github.com/nodenv/nodenv) to manage Node versions in development
 
+:::warning
+
+**Replaced by [ADR 0081](0081-use-asdf-to-manage-node-and-golang-versions-in-development.md)**
+
+:::
+
 `nodenv` makes it easy for developers to upgrade Node in their development
 environments.
 

docs/adrs/0056-use-asdf-to-manage-golang-versions-in-development.md

@@ -3,6 +3,12 @@ title: 0056 Use ASDF To Manage Golang Versions In Development
 ---
 # Use ASDF To Manage Golang Versions In Development
 
+:::warning
+
+**Replaced by [ADR 0081](0081-use-asdf-to-manage-node-and-golang-versions-in-development.md)**
+
+:::
+
 There are many tools for managing versions of developer tools on developer machines. [brew](https://brew.sh/), [nodenv](https://github.com/nodenv/nodenv), [g](https://github.com/stefanmaric/g), etc. Historically MilMove has used brew for many things, but for node and golang this has lead to problems. Because of the issues around requiring specific versions of node and golang brew has caused more headaches than it is worth dealing with. This lead to [ADR 0046 Use nodenv](0046-use-nodenv.md), which solved the problem for node. However we don't have one for golang. So this ADR aims to provide a recommendation towards managing golang release versions in development.
 
 ## Considered Alternatives

docs/adrs/0081-use-asdf-to-manage-node-and-golang-versions-in-development.md

@@ -0,0 +1,61 @@
+---
+title: 0081 Use ASDF to Manage Node and Golang versions in Development
+---
+
+# Use ASDF to Manage Node and Golang versions in Development
+
+:::info
+
+This ADR supersedes [ADR-0046](0046-use-nodenv.md) and [ADR-0056](0056-use-asdf-to-manage-golang-versions-in-development.md)
+
+:::
+
+## Considered Alternatives
+
+* Do nothing, keep using asdf for golang and nodenv for node
+* Use asdf to manage golang and node versions
+
+## Decision Outcome
+
+* Chosen Alternative: Use [asdf](https://asdf-vm.com/) to manage golang and node versions
+
+ADR-0056 notes that the original author would like to see asdf used for other tools (presumably such as node)
+
+> Admittedly we are not yet taking advantage of `asdf` for other tools, but I would like to see that happen.
+
+ADR-0056 also lists the following as a disadvantage of using asdf for golang and node:
+
+> installing node, yarn, or golang with asdf and another one of the similar tools can cause conflicts depending on which
+> of the version manager tools is first in a particular path.
+
+This is actually an advantage of using asdf, since one of the difficulties of managing asdf _and_ node is the obfuscation
+of which version will be shimmed by which tool. Picking and using _one_ tool is the solution. Since asdf is already required
+for managing go, and it is capable of managing node, it is the logical choice.
+
+If you have a capable tool, Alton Brown would recommend throwing the redundant "unitasker" out:
+> I have railed against unitaskers for 20 years.
+>
+> I've come around to liking them as strategic gifts for people you don't like.
+> - [Alton Brown on NPR's All Things Considered](https://www.npr.org/sections/thesalt/2015/12/23/460833325/the-unitasker-kitchen-gadgets-alton-brown-loves-to-loathe)
+
+## Pros and Cons of the Alternatives
+
+### Do nothing, keep using asdf for golang and nodenv for node
+
+* `+` requires no effort or decision energy
+* `+` has no impact on day-to-day operations of any onboarded engineers
+* `+` has no chance of introducing new issues because no changes would be made
+* `-` keeps relatively higher cognitive load around tooling
+* `-` Truss seems to prefer asdf on newer projects, so engineers onboarding from another project in the future will likely have to juggle multiple node version managers
+* `-` Provides no incentive to revisit onboarding instructions and scripting, which is [currently outdated or over-engineered, even for existing installation of golang via asdf](https://github.com/transcom/mymove/pull/11053/files#r1261749313)
+
+### Use asdf to manage golang and node versions
+
+* `+` asdf is already used for managing golang, so all engineers are familiar with the tool and are using it today
+* `+` simplifies environment setup
+* `+` reduces the number of tools required to maintain the project
+* `+` can be rolled out such that engineers can continue using nodenv until they choose to switch
+* `+` switching from nodenv to asdf is trivial
+* `+` Truss seems to prefer asdf on newer projects, so engineers onboarding from another project in the future will not likely have to juggle multiple node version managers
+* `-` without proper socialization and documentation updates, could add confusion
+* `-` changes core tooling that engineers have likely been using for some time

docs/backend/guides/how-to/manage-golang-with-asdf.md

@@ -35,14 +35,9 @@ Run `asdf install` to install the binary for the currently required version of g
 
 ### Configure global use of golang version
 
-Run `cat .tool-versions` to output what version of go we should be using
+Run `cat .tool-versions` or view the `.tool-versions` file in your editor to output what version of go we should be using
 
-```sh
-❯ cat .tool-versions
-golang 1.15.10
-```
-
-Then run `asdf global golang 1.15.10`
+Then run `asdf global golang <version>` where `<version>` is the version defined in `.tool-versions`
 
 ### Reload your shell
 
@@ -54,7 +49,7 @@ Run `asdf current` and `which go` to verify they point to the right versions. Th
 
 ```sh
 ❯ asdf current
-golang          1.15.10          /Users/john/projects/dod/mymove/.tool-versions
+golang          <version>          /Users/john/projects/dod/mymove/.tool-versions
 
 ❯ which go
 /Users/john/.asdf/shims/go
@@ -112,7 +107,7 @@ then run `source ~/.bash_profile` in the terminal to reload.
 If you are getting can't compile because library was compiled for `old version of go` vs `current version of go`. You probably should exit your shell and open a new one. Also ensure the below are in your shell's rc file.
 
 ```sh
-# Ensure that the `asdf.sh` file is run first before envoking any `go *`
+# Ensure that the `asdf.sh` file is run first before invoking any `go *`
 # commands.
 source $(brew --prefix asdf)/libexec/asdf.sh
 

docs/backend/guides/how-to/switch-from-nodenv-to-asdf.md

@@ -0,0 +1,36 @@
+---
+title: How to Switch from nodenv to asdf for Managing Node Versions
+---
+
+# How to Switch from [nodenv](https://github.com/nodenv/nodenv) to [asdf](https://asdf-vm.com/) for managing Node Versions
+
+[ADR-0081](../../../adrs/0081-use-asdf-to-manage-node-and-golang-versions-in-development.md) recommends using asdf for
+both Node and Go. Many folks are likely using nodenv today, and have the option to migrate at a time of their choosing.
+
+This guide assumes you already have asdf installed (for Go). If not, install asdf first.
+
+1. Uninstall nodenv
+
+   ```
+   $ brew uninstall nodenv
+   ```
+
+2. Remove nodenv references from your shell profile file (e.g. `.zshrc`). You likely have a `eval "$(nodenv init -)"` there.
+
+3. Install the asdf nodejs plugin
+
+   ```
+   asdf plugin add nodejs
+   ```
+
+4. Ensure project tool versions for the project are installed, by running the following from inside the project directory.
+
+   ```
+   asdf install
+   ```
+
+   Within mymove-docs, this will install the correct version of node.
+   Within mymove, this will install the correct version of go and node.
+
+   ASDF will automatically use the version(s) defined in `.tool-versions` whenever you are in a directory that has a `.tool-versions` file, so long as it has been installed, just like nodenv.
+

docs/backend/guides/how-to/upgrade-node.md

@@ -9,7 +9,7 @@ sidebar_position: 7
 3. In the transcom/mymove repo, create a PR to update node. [Here's an example](https://github.com/transcom/mymove/pull/6878) && [this PR](https://github.com/transcom/mymove/pull/6904)
 
 Things to modify:
-* Bump the `.node_version`
+* Bump the nodejs version in `.tool-versions` and `.node_version` (some folks may still be using nodenv to manage node)
 * Modify the instances of `milmove/circleci-docker:milmove-app-` and replace the hash w/ the one found in step 2. (I used the PR branch name rather than hash so it would pull any changes I made over on the `circleci-docker` PR without having to update the hash each time I made a change)
 * update `check-node-version` and `prereqs`
 * Do a find and replace to update references of the prior node version with the new node version

docs/backend/guides/troubleshoot-precommit-hook-failures.md

@@ -26,7 +26,7 @@ If they are not installed:
 ## Errors and Solutions
 
 ### 1. Error: Installing environment
-For an error about installing the environment, try ensuring your nodenv is set correctly.
+For an error about installing the environment, try ensuring your nodenv or asdf manage node version is set correctly.
 This is what the error looks like, it stalls here for a while….
 ```
 $ pre-commit install-hooks
@@ -35,19 +35,43 @@ $ pre-commit install-hooks
 [INFO] This may take a few minutes...
 ```
 #### Solution 1
-For this error you may need to set your global nodenv version
-
-Check the current versions,
-```
-~/$ cat .node-version
-12.21.0
-```
+For this error you may need to set your global node version.
+
+Check the current versions from inside the mymove folder,
+
+* asdf
+  ```
+  ~/mymove$ cat .tool-versions
+  golang <project-go-version>
+  nodejs <project-node-version>
+  ```
+
+  Verify which version of nodejs asdf is using (the version with the asterisk is currently selected)
+  ```
+  ~/mymove$ asdf list nodejs
+  <lower-node-version>
+  *<current-node-version>
+  <higher-node-version>
+  ```
+
+* nodenv
+  ```
+  ~/mymove$ cat .node-version
+  <project-node-version>
+  ```
 
 Outside mymove folder, set the global version,
-```
-~/mymove$ cd ..
-~/$ nodenv global 12.21.0
-```
+* asdf
+  ```
+  ~/mymove$ cd ..
+  ~/$ asdf global nodejs <project-node-version>
+  ```
+* nodenv
+  ```
+  ~/mymove$ cd ..
+  ~/$ asdf global <project-node-version>
+  ```
+
 
 Then inside mymove,
 ```
@@ -139,7 +163,7 @@ This could be due to the build failing. Try `make server_build` to check.
 
 #### Nix Error: SSL Certificate verify failed
 
-This can happen because of the way certs need to be handled in this project and `nix`. 
+This can happen because of the way certs need to be handled in this project and `nix`.
 
 #### Solution
 To get around this issue, you can try running:

docs/backend/setup/common-errors-and-solutions.md

@@ -8,7 +8,7 @@ Having trouble running mymove locally? This page collects common errors and thei
 
 ## Migrations
 
-### Invalid migration path 
+### Invalid migration path
 
 ```
 2020-08-05T10:41:00.589-0500	INFO	milmove/migrate.go:61	checking migration config	{"git_branch": "main", "git_commit": "c42a3ef9a458e5b9de94fa3507b6c2f43b209856"}
@@ -30,21 +30,18 @@ The engine "node" is incompatible with this module. Expected version "12.21.0".
 ```
 
 #### Solution
-The project uses node version `12.21.0`. Use `nodenv` to manage your node versions and easily switch between them.
+The project uses the node version specified in `.tool-versions`. Use `asdf` to manage your node versions and easily switch between them.
 
-* Install `nodenv`: https://github.com/nodenv/nodenv
-  * `brew install nodenv`
+* Install `asdf`: https://asdf-vm.com/
+  * `brew install asdf`
 * Install the correct version of Node
-  * `nodenv install 12.21.0`
-* Set version of Node
-  * `nodenv local 12.21.0`
-
-**Note**: Make sure you've appended `eval "$(nodenv init -)"` to your shell rc. Read through the [official docs](https://github.com/nodenv/nodenv#installation) when installing `nodenv`.
+  * `asdf plugin add nodejs`
+  * `asdf install`
 
 ## Compiling
 
 ## The client doesn't reflect my new changes or will not build locally
-The client server is detecting a build problem. You fix it, but it does not see the new code and the problem remains. Sometimes, no new build is triggered. 
+The client server is detecting a build problem. You fix it, but it does not see the new code and the problem remains. Sometimes, no new build is triggered.
 
 This can manifest in a couple of ways, appearing to be a code problem or potential a missing npm package and various other "weird" symptoms. Sometimes it occurs on branch switching without shutting down the server first.
 
@@ -64,6 +61,6 @@ You may see an error message stating `Conflicting order` from a plugin such as t
 
 The way to resolve these errors is to figure out what the common parents of these components or files are and where they are used.  You will likely need to reorder the import statements of these resources in a consistent fashion.  Because we are using create-react-app we can't easily suppress this warning in a webpack config.
 
-For more details you can consult this [GitHub issue](https://github.com/facebook/create-react-app/issues/5372).  
+For more details you can consult this [GitHub issue](https://github.com/facebook/create-react-app/issues/5372).
 
 

docs/backend/setup/run-pre-commit-hooks.md

@@ -15,28 +15,6 @@ Pre-commit can be run by running the following command in terminal:
 
 If you would like to run an individual hook, for example if you want to only run *prettier*: `pre-commit run prettier -a`
 
-## Specifying and updating the Node version in the config
-
-By default, `pre-commit` uses the system-installed versions of languages. We prefer to manage versions with language managers such as `nodenv` and `asdf`. By default `nodenv` doesn't install Node system-wide, which can cause `pre-commit install-hooks` to hang without explanation. The solution is to either install the language globally (not ideal), or tell `pre-commit` to use a specific version of a language. We can either use the `language_version` key within a specific hook, or if we expect all Node hooks to use the same version, we can define a top-level `default_language_version` attribute where you can specify multiple languages and their versions, like this:
-```yaml
-default_language_version:
-  # this should match the version in .node-version at the root of this project
-  node: 12.21.0
-
-repos:
-  - repo: local
-    hooks:
-      - id: go-version
-        name: go version
-        entry: scripts/check-go-version
-        language: script
-        types: [go]
-```
-
-This specific language version should match the one we use on the project. For Node, this is defined in `.node-version`. When we upgrade Node, we should remember to update the `pre-commit` config file as well.
-
-Currently, it looks like `pre-commit` only supports Python, Node, and Ruby for specific language versions. See the [pre-commit documentation](https://pre-commit.com/#overriding-language-version) for more details.
-
 ## Editor Integration
 
 1. `golangci-lint` supports various [editors](https://github.com/golangci/golangci-lint/#editor-integration)