Merge pull request #7410 from andysterland/dev/andster/devinitDocUpdates

American-Dipper · web-flow · commit 5e74505b202d · 2020-11-09T16:15:41.000-08:00
Expanding devinit docs
diff --git a/docs/devinit/devinit-and-codespaces.md b/docs/devinit/devinit-and-codespaces.md
@@ -16,29 +16,49 @@ ms.technology: devinit
 
 devinit is a great compliment to [GitHub Codespaces](https://github.com/features/codespaces) and devinit can be used to get a codespace setup so contributors can build, run, and debug right away.
 
-To integrate with GitHub Codespaces, `devinit` needs to be called from the `postCreateCommand` defined in a `.devcontainer.json` file placed in the repo root. The string(s) in `postCreateCommand` are executed in the default shell, after the repo is cloned in the codespace. You can read more about `postCreateCommand` in the GitHub Codespaces [customization documentation](https://docs.github.com/github/developing-online-with-codespaces/configuring-codespaces-for-your-project). To add the `devinit` command, you can add `devinit init` to the `postCreateCommand` as shown in the examples below.
+> [!IMPORTANT]
+> Before integrating devinit with your codespace, you first need to make sure you have a `.devinit.json` file that defines your dependencies. For more information on how to create a `.devinit.json`, read the [getting started documentation](getting-started-with-devinit.md).
+
+Inside of a GitHub Codespace, your application is built and run in the cloud. Being in the cloud means that your application doesn't have access to local resources on your machines. These include tools or programs that you have installed locally. If your application needs any system-wide dependencies to be installed or configured, it needs to be done on each codespace. The easiest way to achieve that is to use a `.devinit.json` file.
+
+To make sure that a codespace is created with the dependencies your application needs, `devinit` needs to be run when the codespace is created. This can be done by calling `devinit init` from the `postCreateCommand` defined in a `.devcontainer.json` file placed in the repository root. The string(s) in `postCreateCommand` are executed in the default shell, after the repo is cloned in the codespace. You can read more about `postCreateCommand` in the GitHub Codespaces [customization documentation](https://docs.github.com/github/developing-online-with-codespaces/configuring-codespaces-for-your-project). To add the `devinit` command, you can add `devinit init` to the `postCreateCommand` as shown in the examples below.
 
 You can also execute `devinit init -f <path to .devinit.json>` from the Visual Studio Integrated Terminal once connected to your codespace.
 
 ## Examples
 
-### With a .devinit.json file
-In this example, the _.devcontainer.json_ file below is placed in the repo root alongside the _.devinit.json_ file. The files can also be placed in a _.devcontainer_ directory.
+In both examples below, the `.devinit.json` is in the repository root alongside `.devcontainer.json`.
+
+### With a .devcontainer.json file
+
+In this example, the `.devcontainer.json` file below is placed in the repo root alongside the `.devinit.json` file. The files can also be placed in a `.devcontainer` directory.
 
 ```json
 {
   "postCreateCommand": "devinit init"
 }
 ```
 
+When the `.devinit.json` is in another directory, the -f flag may be used.
+
+```json
+{
+  "postCreateCommand": "devinit init -f path\\to\\.devinit.json"
+}
+
+```
+
 ```json
 {
   "postCreateCommand": ["<some other command>", "devinit init"]
 }
 ```
 
+You can find more examples of using devinit in our [documentation](sample-all-tool.md) and on GitHub in the [.NET Core example](https://github.com/microsoft/devinit-example-dotnet-core) and [Node.js example](https://github.com/microsoft/devinit-example-nodejs) repositories.
+
 ### As commands
-In this example _.devcontainer.json_ file below is placed in the repo root and `devinit run` is being called programmatically to run a tool  
+
+In this example, `.devcontainer.json` file below is placed in the repo root and `devinit run` is being called directly from the command line to run an individual tool.  
 
 ```json
 {
@@ -48,13 +68,13 @@ In this example _.devcontainer.json_ file below is placed in the repo root and `
 
 ### From a terminal prompt
 
-When the current working directory contains a _.devinit.json_ file.
+When the current working directory contains a `.devinit.json` file.
 
 ```console
 devinit init
 ```
 
-When the _.devinit.json_ is in another directory.
+When the `.devinit.json` is in another directory.
 
 ```console
 devinit init -f path/to/.devinit.json
diff --git a/docs/devinit/devinit-commands.md b/docs/devinit/devinit-commands.md
@@ -20,15 +20,15 @@ ms.technology: devinit
 devinit init
 ```
 
-Initialize the environment by running the tools specified in a [_.devinit.json_](devinit-json.md) file in the current working directory.  
+Initialize the environment by running the tools specified in a [.devinit.json](devinit-json.md) file.
 
 ### Options for init
 
 Optional options for the `devinit init` command.
 
 | Argument             | Required | Description                                                               |
 |----------------------|----------|---------------------------------------------------------------------------|
-| -f,--file            | No       | Path to the _.devinit.json_ file.                                         |
+| -f,--file            | No       | Path to the `.devinit.json` file.                                         |
 | --error-action       | No       | Specifies how to handle errors. Options: Stop, Ignore, Continue (default).|
 | -v,--verbose         | No       | Emit verbose output.                                                      |
 | -n,--dry-run         | No       | Dry run.                                                                  |
@@ -92,6 +92,10 @@ Specifies the action to take if a tool returns a non-zero exit code. The valid v
 | ignore   | Continue processing other tools after emitting a warning to standard output. DevInit process exit code should always be zero (success). The `ignore` setting ignores all errors.                                                                                                      |
 | stop     | Emits an error to standard error and stops processing tools. The devinit.exe exit code is non-zero (failure). This is similar to the continue error action, but processing is halted at the first error encountered. `stop` is the default error-action for all commands except init. |
 
+#### --dry-run switch
+
+Echo tool commands that would be run. Some tools may take further action as documented for that tool. 
+
 #### --verbose switch
 
 Emit verbose output to standard output. If the tool to be executed supports a verbose option, propagate the verbose switch to the tool.
diff --git a/docs/devinit/devinit-json.md b/docs/devinit/devinit-json.md
@@ -14,9 +14,11 @@ ms.technology: devinit
 ---
 # devinit configuration file
 
+The `.devinit.json` file defines the system-wide dependencies that your application needs in order to run and build. System-wide dependencies are things like Node.js, SQL Server, IIS, RabbitMQ, Docker, etc. These are the sort of things you would normally install on your dev box that aren't installed by a specific repo. It's not a place to define application-specific dependencies like you would in package managers such as NuGet or NPM. It is, however, a place to define that you need those package managers.
+
 ## File location
 
-The `devinit.exe init` command is driven via the _.devinit.json_ file. By default, `devinit.exe` looks for the file in the following locations:
+The `devinit init` command is driven via the `.devinit.json` file. By default, `devinit` looks for the file in the following locations:
 
 * {current-directory}\\.devinit.json
 * {current-directory}\\devinit.json
@@ -30,7 +32,7 @@ The `devinit.exe init` command is driven via the _.devinit.json_ file. By defaul
 > [!NOTE]
 > If multiple default files are found, then devinit will use the file that appears first in the above list.
 
-The _.devinit.json_ file can also be specified explicitly via the `--file`/`-f` option.
+The `.devinit.json` file can also be specified explicitly via the `--file`/`-f` option.
 
 ### Directories and relative paths
 
diff --git a/docs/devinit/getting-started-with-devinit.md b/docs/devinit/getting-started-with-devinit.md
@@ -14,15 +14,19 @@ ms.technology: devinit
 ---
 # Getting Started with devinit
 
+devinit is a tool that you can use to enable anyone to get to code and be productive in your repository by running a simple command. You can use devinit to define all the system-wide dependencies that your repository needs something like SQL server, Node.js, Docker, or IIS. Devinit can invoke other tools and package managers to install what your repository needs. You define those dependencies in a JSON file named [.devinit.json](devinit-json.md) and then the next person to use your repository just has to run [`devinit init`](devinit-commands.md#init) to install all those dependencies. So, rather than spending half a day onboarding onto a new repository, it can be done in minutes.
+
+devinit isn't a package manager or a Virtual Machine (VM) configuration tool in and of itself. It's a task runner for a manifest file, named [.devinit.json](devinit-json.md), that defines the system-wide dependencies that your application needs. To install these dependencies, devinit makes use of tools that you might already be using, such as [Chocolatey](https://chocolatey.org). You can review the available tools in the [full list](devinit-tool-list.md). By using these tools rather than distributing software directly, devinit gives you the convenience of using the tool of your choice and enabling you to use existing configurations, for example, a [packages.config](https://chocolatey.org/docs/commands-install#packagesconfig) file for Chocolatey.  
+
 ## Step 1: Get devinit
 
 devinit is currently only available as part of GitHub Codespaces when using Visual Studio and is accessible from the integrated terminal in Visual Studio. In the future, devinit will be available as part of Visual Studio.
 
 ## Step 2: Define your environment
 
-The most important step is to define your 'developer' environment in a [_.devinit.json_ file](devinit-json.md). This file will be used by devinit to create your environment when you run `devinit init`.
+The most important step is to define your 'development' environment in a [.devinit.json file](devinit-json.md). This file will be used by devinit to create your environment when you run `devinit init`.
 
-For this step, think about the instructions you'd give someone to get up and running with a project repository. For example, do they need to have SQL installed? A specific version of .NET Core? etc. Then for each of those dependencies, look for a corresponding devinit tool in the [list of tools](devinit-tool-list.md) and add that to the repository's _.devinit.json_ file.
+For this step, think about the instructions you'd give someone to get up and running with a project repository. For example, do they need to have SQL installed? A specific version of .NET Core? And so on. Then for each of those dependencies, look for a corresponding devinit tool in the [list of tools](devinit-tool-list.md) and add that to the repository's `.devinit.json` file. You can also see a selection of examples over in the [samples documentation](sample-readme.md).
 
 ## Step 3: Enjoy!
 
@@ -32,4 +36,4 @@ Now all someone has to do after cloning your repo is run `devinit init`.
 devinit init
 ```
 
-If you're using [GitHub Codespaces](https://github.com/features/codespaces), you can configure `devinit init` to run automatically when the codespace is provisioned. To learn more have a look at the [devinit and GitHub Codespaces documentation](devinit-and-codespaces.md).
+If you're using [GitHub Codespaces](https://github.com/features/codespaces), you can configure `devinit init` to run automatically when the codespace is provisioned. To learn more, have a look at the [devinit and GitHub Codespaces documentation](devinit-and-codespaces.md).
diff --git a/docs/devinit/sample-dotnet-runtime.md b/docs/devinit/sample-dotnet-runtime.md
@@ -39,7 +39,7 @@ The _packages.config_ file is a [Chocolatey](https://chocolatey.org/) file that
 
 ## .devinit.json
 
-Contents of the [_.devinit.json_](devinit-json.md) file. This file needs to be in the same folder as _.devcontainer.json_ file.
+Contents of the [`.devinit.json`](devinit-json.md) file. This file needs to be in the same folder as the _.devcontainer.json_ file.
 
 ```json
 {
diff --git a/docs/devinit/sample-eshoponweb.md b/docs/devinit/sample-eshoponweb.md
@@ -28,7 +28,7 @@ dotnet ef database update -c appidentitydbcontext -p src\Infrastructure\Infrastr
 
 ## .devinit.json
 
-Contents of the [_.devinit.json_](devinit-json.md) file. This file needs to be in the same folder as _.devcontainer.json_.
+Contents of the [`.devinit.json`](devinit-json.md) file. This file needs to be in the same folder as _.devcontainer.json_.
 
 ```json
 {
diff --git a/docs/devinit/sample-private-preview.md b/docs/devinit/sample-private-preview.md
@@ -1,6 +1,6 @@
 ---
-title: Private Preview 
-description: Example customizations used in the GitHub Codespaces Visual Studio preview beta repo.
+title: Private beta 
+description: Example customizations used in the GitHub Codespaces Visual Studio preview beta repository.
 ms.date: 08/28/2020
 ms.topic: reference
 author: andysterland
@@ -12,13 +12,13 @@ monikerRange: ">= vs-2019"
 ms.prod: visual-studio-windows
 ms.technology: devinit
 ---
-# Private preview
+# Private beta
 
 This example illustrates how to customize a codespace for Visual Studio to have the same features as the initial [GitHub Codespaces](https://github.com/features/codespaces) private beta.
 
 ## .devinit.json
 
-Contents of the [_.devinit.json_](devinit-json.md) file. This file needs to be in the same folder as _.devcontainer.json_.
+Contents of the [`.devinit.json`](devinit-json.md) file. This file needs to be in the same folder as _.devcontainer.json_.
 
 ```json
 {
diff --git a/docs/devinit/sample-readme.md b/docs/devinit/sample-readme.md
@@ -20,7 +20,7 @@ The table below contains a list of all the currently available examples for usin
 |---------------------------------------------------|------------------------------------------------------------------------------------------------------------------------------|---|
 | [**All tools**](sample-all-tool.md)               | Example of using all the tools.                                                                                              |   |
 | [**eShopOnWeb**](sample-eshoponweb.md)            | Example of customizing the [dotnet-architecture/eshoponweb](https://github.com/dotnet-architecture/eShopOnWeb) app.          |   |
-| [**Private Preview**](sample-private-preview.md)  | Example of the customizations used in the GitHub Codespaces Visual Studio private beta.                                      |   |
+| [**Private beta**](sample-private-preview.md)     | Example of the customizations used in the GitHub Codespaces Visual Studio private beta.                                      |   |
 | [**Open CV**](sample-opencv.md)                   | Example of the customizations required by the OpenCV project.                                                                |   |
 | [**.NET Core Runtime**](sample-dotnet-runtime.md) | Example of the customizations required by the .NET Core Runtime [dotnet/runtime](https://github.com/dotnet/runtime) project. |   |
 | [**.NET Core App**](sample-dotnet-core.md)        | Example of a repository that uses devinit to install the required .NET Core SDK.                                             |   |
diff --git a/docs/devinit/toc.yml b/docs/devinit/toc.yml
@@ -81,7 +81,7 @@
       href: sample-eshoponweb.md
     - name: OpenCV repo
       href: sample-opencv.md
-    - name: Codespaces private preview
+    - name: Codespaces private beta
       href: sample-private-preview.md
     - name: .NET Core App
       href: sample-dotnet-core.md

Original file line number	Diff line number	Diff line change
`@@ -39,7 +39,7 @@ The _packages.config_ file is a [Chocolatey](https://chocolatey.org/) file that`
`39`	`39`
`40`	`40`	`## .devinit.json`
`41`	`41`
`42`		`-Contents of the [_.devinit.json_](devinit-json.md) file. This file needs to be in the same folder as _.devcontainer.json_ file.`
	`42`	+Contents of the [`.devinit.json`](devinit-json.md) file. This file needs to be in the same folder as the _.devcontainer.json_ file.
`43`	`43`
`44`	`44`	```json
`45`	`45`	`{`
Original file line number	Diff line number	Diff line change
`@@ -28,7 +28,7 @@ dotnet ef database update -c appidentitydbcontext -p src\Infrastructure\Infrastr`
`28`	`28`
`29`	`29`	`## .devinit.json`
`30`	`30`
`31`		`-Contents of the [_.devinit.json_](devinit-json.md) file. This file needs to be in the same folder as _.devcontainer.json_.`
	`31`	+Contents of the [`.devinit.json`](devinit-json.md) file. This file needs to be in the same folder as _.devcontainer.json_.
`32`	`32`
`33`	`33`	```json
`34`	`34`	`{`