add developer instructions

docs/developer_guide.md

@@ -1 +1,129 @@
-TODO
+# Developer Guide
+
+## Building the code
+
+Building tye from source allows you to experiment, and to contribute your improvements back to the project.
+
+## Install pre-requisites
+
+Tye uses [Arcade](https://github.com/dotnet/Arcade) to build. As of right now there are no prerequisites needed to build and edit the code. 
+
+We recommend using whatever developer tools you like for C# and .NET development. Visual Studio has [free versions](https://visualstudio.microsoft.com/downloads/) and VS Code has an available C# extension.
+
+Your development environment will likely require the [.NET SDK](https://dotnet.microsoft.com/download) to be installed, though the command line build will use a local copy of .NET.
+
+### Integration test pre-requisites
+
+Our integration tests will make use of Docker's command line tools for some functionality. You can find the appropriate installer for Docker [here](https://hub.docker.com/search?q=&type=edition&offering=community&sort=updated_at&order=desc).
+
+## Clone the source code
+
+For a new copy of the project, run:
+
+```sh
+git clone https://github.com/dotnet/tye
+```
+
+## Opening in Visual Studio
+
+Before opening our .sln files in Visual Studio or VS Code, we recommend performing the following actions.
+
+1. Executing the following on command-line:
+
+   ```ps1
+   .\build.cmd
+   ```
+
+   This will download the required tools and build the entire repository once. At that point, you should be able to open .sln files to work on the projects you care about.
+
+   > :bulb: Pro tip: you will also want to run this command after pulling large sets of changes. On the master branch, we regularly update the versions of .NET Core SDK required to build the repo.
+   > You will need to restart your editor every time we update the .NET Core SDK.
+
+2. Use the `startvs.cmd` script to open Visual Studio .sln files. This script first sets the required environment variables.
+
+## Opening in Visual Studio Code
+
+Using Visual Studio Code with this repo requires setting environment variables on command line first.
+Use these command to launch VS Code with the right settings.
+
+On Windows (requires PowerShell):
+
+```ps1
+# The extra dot at the beginning is required to 'dot source' this file into the right scope.
+
+. .\activate.ps1
+code .
+```
+
+On macOS/Linux:
+
+```bash
+source activate.sh
+code .
+```
+
+Note that if you are using the "Remote-WSL" extension in VSCode, the environment is not supplied
+to the process in WSL.  You can workaround this by explicitly setting the environment variables
+in `~/.vscode-server/server-env-setup`.
+See https://code.visualstudio.com/docs/remote/wsl#_advanced-environment-setup-script for details.
+
+## Building on command-line
+
+You can also build the entire project on command line with the `build.cmd`/`.sh` scripts.
+
+On Windows:
+
+```ps1
+.\build.cmd
+```
+
+On macOS/Linux:
+
+```bash
+./build.sh
+```
+
+### Using `dotnet` on command line in this repo
+
+Because we are using a local version of .NET Core, you have to set a handful of environment variables
+to make the .NET Core command line tool work well. You can set these environment variables like this
+
+On Windows (requires PowerShell):
+
+```ps1
+# The extra dot at the beginning is required to 'dot source' this file into the right scope.
+
+. .\activate.ps1
+```
+
+On macOS/Linux:
+
+```bash
+source ./activate.sh
+```
+
+## Running tests on command-line
+
+Tests are not run by default. Use the `-test` option to run tests in addition to building.
+
+On Windows:
+
+```ps1
+.\build.cmd -test
+```
+
+On macOS/Linux:
+
+```bash
+./build.sh --test
+```
+
+## Using local builds
+
+The easiest way to use a custom build of tye is to `dotnet run -p <path to tye projet>`. 
+
+If you want to install your build as a dotnet global tool, that is possible as well. Building the repo will create packages in the artifacts folder that can be used.
+
+```sh
+dotnet install tye -g --version "0.1.0-dev" --add-source ./artifacts/packages/Debug/Shipping
+```