adding more info on forking and testing (#65)

CONTRIBUTING.md

@@ -23,25 +23,39 @@ The core team will test the change to validate it before merging it.
 
 ## Repository Structure
 
-Scripts are named with dev_[MAJOR_AREA]_[MINORAREA].
+Recipe scripts are named with **dev_[MAJOR_AREA]_[MINORAREA]**.
-The Minor Area is optional. Currently the scripts are completely self contained - there is no script chaining. It would be useful to move to a tree model, and we'll update these instructions if/when that happens.
+The Minor Area is optional.
 
 Examples
 - dev_web_nodejs
 - dev_app_android 
 - dev_ml
 
-Current Major Areas
+Examples of Major Areas
 - web
 - app
 - ml (machine learning)
 - iot
-- backend
 
-Minor Area is open
+The recipe scripts are intended to be short.  Most of script logic should live in helper scripts which live in the **scripts** folder.  You can add to existing helper scripts or make new helper scripts.
+
+If you make a new recipe script that includes additional manual steps please create a new folder which includes your new script and a Readme with these instructions.
+
+## Testing a script change
+Testing script changes is best done on a clean machine.  One way to do this without modifying your primary environment is via a Virtual Machine.
+
+Here's an example of how to set up a test workflow
+1. [Install Hyper-V Manager](https://docs.microsoft.com/en-us/virtualization/hyper-v-on-windows/quick-start/enable-hyper-v)
+1. Create a new VM using [Quick Create](https://docs.microsoft.com/en-us/virtualization/hyper-v-on-windows/quick-start/quick-create-virtual-machine)
+1. Save a [checkpoint](https://docs.microsoft.com/en-us/virtualization/hyper-v-on-windows/user-guide/checkpoints) as your 'clean' restore point
+
+When you've made script changes to your fork you can run the updated script in this clean VM.  In this VM open a browser window and paste the 1-click link which will run your modified recipe script.
+
+`http://boxstarter.org/package/nr/url?https://raw.githubusercontent.com/GITHUB_DOMAIN/windows-dev-box-setup-scripts/YOUR_BRANCH/dev_web_nodejs.ps
+`
+
+When you've finished testing, in Hyper-V Manager reset this VM to the clean checkpoint so it's ready the next time you test a script.
 
-If you have a change request for Major Area please let us know by filing an issue.
 
-If the script has additional steps please create a folder for your script and include a Readme with these instructions.
 
 Thank you!

README.md

@@ -9,10 +9,36 @@ These scripts leverage two popular open source projects.
 Boxstarter is a wrapper for Chocolatey and includes features like managing reboots for you. We're using the Boxstarter web launcher to start the installation process:<br/>
 https://boxstarter.org/Learn/WebLauncher
 
+## Project structure
+The script code is organized in a hierarchy
+
+**Recipes**
+A recipe is the script you run.  It calls multiple helper scripts.  These currently live in the root of the project (dev_app.ps1, dev_webnodejs.ps1, etc.) 
+
+**Helper Scripts**: A helper script performs setup routines that may be useful by many recipes. Recipes call helper scripts (you don't run helper scripts directly).  The helper scripts live in the **scripts** folder
+
+
+## You may want to customize the scripts
+These scripts should cover a lot of what you need but will not likely match your personal preferences exactly. In this case please fork the project and change the scripts however you desire. We really appreciate PR's back to this project if you have recommended changes.
+
+*Note: When you fork make sure to update these variables in your recipe*
+
+`
+$user = "Microsoft";
+$baseBranch = "master";
+`
+
+*You will also need to update the single click URL for your modified script to refer to your fork:*
+
+`http://boxstarter.org/package/nr/url?https://raw.githubusercontent.com/GITHUB_DOMAIN/windows-dev-box-setup-scripts/YOUR_BRANCH/dev_web_nodejs.ps
+`
+
+For more info on testing your changes take a look at the [contribution guidelines](CONTRIBUTING.md).
+
 ## How to run the scripts
 Before you begin, please read the [Legal](#Legal) section.
 
-To run a setup script, click a link in the table below from your target machine. This will download Boxstarter, and prompt you for Boxstarter to run with Administrator privileges (which it needs to do its job). Clicking yes in this dialog will cause the script to begin. You can then leave the job unattended and come back when it's finished.
+To run a recipe script, click a link in the table below from your target machine. This will download the Boxstarter one-click application, and prompt you for Boxstarter to run with Administrator privileges (which it needs to do its job). Clicking yes in this dialog will cause the recipe to begin. You can then leave the job unattended and come back when it's finished.
 
 |Click link to run  |Description  |
 |---------|---------|
@@ -33,6 +59,9 @@ To run a setup script, click a link in the table below from your target machine.
 ## Working with Chocolatey in an organization?
 As an organization, you may not be keen to reach out to the internet. That's fine as with just a few modifications you can still take advantage of these scripts. Visit the [organizational use page](ORGANIZATION.md) to learn how.
 
+## Working in education?
+In a classroom setting it's a great idea to give your students a recipe script so they can all get setup quickly and reliably. You can modify your recipe script to include downloading course materials and sample projects.  To do this, start by forking this project and follow the instructions [here](#you-may-want-to-customize-the-scripts). 
+
 ## Don't have administrative access?
 Are you in an environment where you don't have any administrative access on your machine? No problem, you can still take advantage of Chocolatey and manage "portable" software. You can also use a VM where you may have administrative access (see next section).