Made CONTRIBUTING guide more (windows-)user friendly

Added extra instructions and explanation to make the process a bit friendlier to Windows developers (and people very new to working with JavaScript). Some other explanations with made a bit more verbose, again to help beginner developers.

Author: aGitForEveryone

CONTRIBUTING.md

@@ -1,37 +1,109 @@
 # Contributor Guide
 
 ## Getting Started
+Glad that you decided to make your contribution in Dash. This guide provides instructions to set up and build the Dash repository and describes best practices when contributing to the Dash repository. 
 
-Glad that you decided to make your contribution in Dash, to set up your development environment, run the following commands:
+### Fork the Dash repository
+When contributing to the Dash repository you should always work in your own copy of the Dash repository. Create a fork of the `dev`-branch, to create a copy of the Dash repository in your own GitHub account. See official instructions for [creating a fork](https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/working-with-forks/fork-a-repo) if needed.
+
+Clone the forked repository (either of both options will work). Replace `<your_user_name>` with your user name. 
+```
+git clone https://github.com/<your_user_name>/dash.git
+```
+or
+```
+git clone [email protected]:<your_user_name>/dash.git
+```
+
+When working on a new feature, always create a new branch and create the feature in that branch. For more best practices, read the [Git section](#git).
+
+## Building Dash
+
+### Windows configuration
+The scripts that run during the build process are designed for a Bash terminal. The default terminals on Windows systems are either PowerShell or Command Prompt. However, the build process will fail (potentially bricking you Node environment) when using these terminals. The listed commands should be executed from a Bash terminal, e.g. you can use the Git Bash terminal (which should be installed when installing Git under default settings). Otherwise, you need to find another way to access a Bash terminal. 
+
+<details>
+  
+<summary>Set up JavaScript environment (for JavaScript beginners)</summary>
+
+#### JavaScript introduction
+  If you are new to JavaScript, many aspects of setting up a working environment and working with the new ecosystem can be a bit overwhelming. Especially if Plotly Dash is your first experience with the JavaScript ecosystem. This section is intended to help you set up your JavaScript environment so you can start working with Dash. When setting up JavaScript you will encounter terms as `nvm`, `Node`, and `npm`
+  - `nvm` stands for Node Version Manager. This is a tool that allows you to manage Node installations. Quite convenient if you are working on multiple tools that require different versions of Node.js. `nvm` will allow you to switch between Node installations with a single command. `nvm` is not integrated in Windows so a third-party tool needs to be used. If you don't have one yet, you can start with [NVM for Windows](https://github.com/coreybutler/nvm-windows) (`nvm-windows`). This version manager is widely used and is well recommended.
+  - `Node.js` is the actual JavaScript runtime environment. Visit the [official site](https://nodejs.org/en) for more info. Don't download Node just yet, install it through `nvm`.
+  - `npm` stands for Node Package Manager. This is the largest software registry for JavaScript packages. Check the [official site](https://docs.npmjs.com/about-npm) for more info.
+  
+  #### JavaScript Installation
+  Carefully follow the installation instructions on the [GitHub page](https://github.com/coreybutler/nvm-windows) for NVM for Windows. As recommended by the installation instructions there: uninstall any pre-existsing Node installations. You will run into permission errors otherwise. 
+  After NVM for Windows has been installed, open any terminal of your preference and install Node and npm:
+  ```
+  nvm install latest
+  ```
+  After installation is complete, activate the Node environment (**admin access required**)
+  ```
+  nvm use latest
+  ```
+  Confirm that the activation was successfull
+  ```
+  node -v
+  npm -v
+  ```
+  If these commands are not recognized, close the terminal, re-open a new instance and retry. If the commands return a version number, you have set up your JavaScript environment successfully!
+</details>
+
+<details>
+  <summary> Working with Pycharm </summary>
+  
+  If you work in Pycharm you can open the Dash repo directory as a project (`File -> Open` then browse search for the `dash` directory containing your dash repo, and open the directory as a project). You can configure your Python virtual environment using the Python Interpreter tool. Secondly, you can open the Git Bash terminal in Pycharm and it will automatically activate your selected Python Interpreter in the terminal. You can verify this by executing `pip --version` in the Git Bash terminal, it will show you the path from where pip is run, which is the path where your virtual environment is installed. If you follow these steps, you can skip the first few steps in the overview below.
+</details>
+
+### Build process
+The build process is mostly the same for Windows and Linux systems. Wherever there are differences between the operating systems, it is marked. 
+
+Open a Bash terminal in the `dash` repository, Git Bash terminal for example on Windows:
 
 ```bash
-# in your working directory
-$ git clone [email protected]:plotly/dash.git
-$ cd dash
-$ python3 -m venv .venv/dev
-# activate the virtualenv
-# on windows `.venv\dev\scripts\activate`
-# on some linux / mac environments, use `.` instead of `source`
-$ source .venv/dev/bin/activate
+# Create and activate virtual environment
+#### LINUX ####
+  $ python3 -m venv .venv/dev
+  # on some linux / mac environments, use `.` instead of `source`
+  $ source .venv/dev/bin/activate
+#### WINDOWS ####
+  # Skip this if you manage the Python Interpreter via Pycharm.
+  # Create and activate virtual environment
+  $ python -m venv .venv/dev
+  # on some linux / mac environments, use `.` instead of `source`
+  $ source .venv/dev/scripts/activate
+########
+
 # install dash and dependencies
 $ pip install -e .[ci,dev,testing,celery,diskcache]  # in some shells you need \ to escape []
+
+# Do a clean install of all packages listed in package-lock.json. Package versions will be
+# exactly like stated in the file
 $ npm ci
-# this script will build the dash-core-components, dash-html-components, dash-table,
+
+# Build dash-core-components, dash-html-components, dash-table,
 # and renderer bundles; this will build all bundles from source code in their
 # respective directories. The only true source of npm version is defined
 # in package.json for each package.
-#
-$ npm run build  # runs `renderer build` and `npm build` in dcc, html, table
-# build and install components used in tests
-# on windows, the developer will need to use `npm run first-build` this performs additional first steps
-#
-# Alternatively one could run part of the build process e.g.
-$ dash-update-components "dash-core-components"
+#### LINUX ####
+  $ npm run build  # runs `renderer build` and `npm build` in dcc, html, table
+#### WINDOWS ####
+  # On Windows the build is done via the first-build script. This adds extra steps
+  # that are automatically applied on Linux systems, but not on Windows systems.
+  $ npm run first-build
+########
+
+# When you first clone the repository, and check out a new branch, you must
+# run the full build as above. Later on, when you only work in one part of
+# the library, you could run part of the build process e.g.
+#    $ dash-update-components "dash-core-components"
 # to only build dcc when developing dcc
-# But when you first clone check out a new branch, you must run the full build as above.
-#
+
+# Build and install components used in tests
 $ npm run setup-tests.py # or npm run setup-tests.R
-# you should see dash points to a local source repo
+
+# Verify that Dash is refering to a local source repo
 $ pip list | grep dash
 ```