From 5521d838274f7b12cf3097a82ef206383efbd374 Mon Sep 17 00:00:00 2001
From: Jason Fairchild <jason@fairchild.au>
Date: Tue, 23 Jul 2024 16:05:15 +1000
Subject: [PATCH] WIP

---
 README.md            |   2 +-
 docs/CONTRIBUTING.md | 110 ++++++++++++++++++++++++++++++-------------
 2 files changed, 77 insertions(+), 35 deletions(-)

diff --git a/README.md b/README.md
index 2ff0cce8..adab006c 100644
--- a/README.md
+++ b/README.md
@@ -81,7 +81,7 @@ directory as an argument! See below for installation options.
 
 > [!TIP]  
 > If you are having trouble building Vivify, or you'd like more detailed build
-> instructions, see our [CONTRIBUTING](CONTRIBUTING.md) page
+> instructions, see our [CONTRIBUTING](docs/CONTRIBUTING.md) page
 
 ## Get help
 
diff --git a/docs/CONTRIBUTING.md b/docs/CONTRIBUTING.md
index 0f82a7b4..f285e6e7 100644
--- a/docs/CONTRIBUTING.md
+++ b/docs/CONTRIBUTING.md
@@ -11,32 +11,66 @@ sure you follow the steps below:
 
 ## Setting Up Your Build Environment
 
-### Build Requirements
-
 To build Vivify you need the following dependencies:-
 
+#### MacOS
+
+    TODO: Mac instructions
+
 #### Arch Linux/Manjaro
 
-```sh
-sudo pacman -S --needed jq yarn make zip
-```
+    sudo pacman -S --needed jq yarn make zip
 
 #### Fedora and derivatives
 
-```sh
-sudo dnf install jq yarn make zip
-```
+    sudo dnf install jq yarn make zip
 
-> [!TIP]
-> TODO: Mention linux nodejs issue and refer to following section on nodejs
+> [!NOTE]
+> The version of **Node.js** shipped with some Linux distributions will fail to
+> build **Vivify**, see the section below to install the latest node from **nvm**
+
+## Installing Node.js
+
+Node.js may be available with your OS or in your distros package manager.
+Alternatively you can install the latest version of Node.js using **[Node
+Version Manager](https://github.com/nvm-sh/nvm)** (**nvm**)
+
+To install **nvm** use:-
+
+    curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.7/install.sh | bash
 
-## Nodejs
+You will then need to reload your terminal by either closing it and opening a
+new one or by re-sourcing your run commands (bash eg: `source ~/.bashrc`)
+
+Now you can install the latest version of Node.js:-
+
+    nvm install node
+
+> [!TIP]
+> You can return to the system version of node using `nvm use system`
+>
+> For more details on nvm usage or for troubleshooting installing nvm, visit the
+> nvm [Documentation][1] page
+>
+> [1]:<https://github.com/nvm-sh/nvm?tab=readme-ov-file#node-version-manager--->
 
-***TODO: Talk about nodejs linux broken etc.***
 
 ## Building Vivify
 
-***TODO: Take build steps from readme.md***
+First clone and open the **Vivify** repository
+
+    git clone https://github.com/jannis-baum/Vivify.git
+    cd Vivify
+
+Run `yarn` to download all node dependencies
+
+    yarn
+
+Then build **Vivify** by running `make`
+
+    make
+
+TODO: WIP
 
 ## Running Vivify for Development
 
@@ -46,29 +80,41 @@ live-updates as you are coding.
 
 Using `yarn dev` to run **Vivify** in dev mode will:-
 
-1. Run `vivify-server` on port `3000` instead of the usual port of `31622` so they
-   can be run side by side;
+1. Run `vivify-server` on port `3000` instead of the usual port of `31622` so
+   they can be run side by side;
 2. Automatically reload when you make changes to the code; and
-3. Unlike the installed version, not shut down when there are no connected clients.
+3. Unlike the installed version, not shut down when there are no connected
+   clients.
+
+First, use `yarn` to make sure all node dependencies are up to date
+
+    yarn
+
+Then start the **Vivify** server in dev mode
+
+    yarn dev
 
-```sh
-# Run yarn to update any nodejs / npm package depenencies
-yarn
+Once the development server is running, you can connect as many instances as you
+like using:-
 
-# Start the Vivify server in dev mode
-yarn dev
-```
+    yarn viv .
 
-With the development server running, use:-
+> [!TIP]
+> Using `yarn viv` will connect to the development server on port 3000 instead
+> of running the installed server, and will use the viv executable in the
+> repository
+>
+> You can replace `.` with any path or filename
+
+## Troubleshooting
+
+### Build Error: Could not find the sentinel NODE_SEA_FUSE_fce680ab2cc467b6e072b8b5df1996b2
 
-```sh
-# Connect an instance to your Vivify dev server
-yarn viv
-```
+Cause: This happens on some Linux distros when using the distro packaged
+versions of Node.js
 
-instead of your installed Vivify executable. This will (1) connect to the
-development server on port 3000 instead of running the installed server, and (2)
-use the `viv` executable in the repository.
+Resolution: Install the latest version of Node.js using nvm, See the
+** Installing Node.js** section above
 
 ## Testing rendering
 
@@ -76,10 +122,6 @@ You can find files to test Vivify's rendering/parsing capabilities in the
 [`tests/`](tests/) directory. Please make sure to add to this in case you add
 anything new related to this.
 
-## Troubleshooting
-
-***TODO: Common errors and build problems here?***
-
 ## Writing Markdown
 
 We use