docs: update prerequiste and debug docs

docs/contributing/contributing-code/contributing-code-first-commit/first-commit-00-prerequisites.md

@@ -8,35 +8,56 @@
 
 We support developing on macOS, Linux and Windows with [WSL](https://docs.microsoft.com/windows/wsl/install).
 
+## Package managers
+
+On our supported OSes using a package manager to install these dependencies is a much easier way to keep them updated.
+
+- For macOS, this likely means you should be using [Homebrew](https://brew.sh/).
+- On Linux, use your distribution's package manager.
+
 ## Required installs
 
-This is the list of core dependencies to install for the most common tasks. In general we expect all contributors to have all of these tools present:
+We recommend the usage of either GitHub Codespaces or dev containers to setup your development environment. Here are the links that provide more details:
 
-- [Git](https://git-scm.com/downloads)
+- [Getting started - GitHub Codespaces](../contributing-code-prerequisites/README.md#github-codespaces)
+- [Getting started - Dev Containers](../contributing-code-prerequisites/README.md#vs-code-and-dev-container)
 
-- Make  
-
-  **Linux**: Install the `build-essential` package:
-  ```bash
-  sudo apt-get install build-essential
-  ```
-  **Mac**:
-  Using Xcode:
-  ```bash  
-  xcode-select --install
-  ```
-  Using Homebrew:
-  ```bash  
-  brew install make
-  ```
+However, you can also install all tools locally. This is the list of core dependencies to install for the most common tasks. In general we expect all contributors to have all of these tools present:
+
+- [Git](https://git-scm.com/downloads)
 - [Go](https://golang.org/doc/install)
 - [Node.js](https://nodejs.org/en/)
+- [Python](https://www.python.org/downloads/)
 - [Golangci-lint](https://golangci-lint.run/usage/install/#local-installation)
+- [jq](https://jqlang.github.io/jq/download/)  
+- Make  
+
+### Install make
 
-## Package managers
-On our supported OSes using a package manager to install these dependencies is a much easier way to keep them updated. 
-- For macOS, this likely means you should be using [Homebrew](https://brew.sh/).
-- On Linux, use your distro's package manager.
+For `make` we advice the following installation steps depending on you OS.
+
+#### Linux
+
+Install the `build-essential` package:
+
+```bash
+sudo apt-get install build-essential
+```
+
+#### Mac
+
+Using Xcode:
+
+```bash  
+xcode-select --install
+```
+
+Using Homebrew:
+
+```bash  
+brew install make
+```
 
 ## Next step
+
 - [Install development tools](first-commit-01-development-tools.md)

docs/contributing/contributing-code/contributing-code-first-commit/first-commit-01-development-tools.md

@@ -6,7 +6,7 @@
 
 ## Editor
 
-This guide covers basic development tasks for Go in Visual Studio Code. The experience with VS Code is high-quality and approachable for newcomers.
+This guide covers basic development tasks for Go in Visual Studio Code (VS Code). The experience with VS Code is high-quality and approachable for newcomers.
 
 Alternatively, you can choose whichever editor you are most comfortable for working on Go code. Feel free to skip this section if you want to make another choice.
 
@@ -15,6 +15,8 @@ Alternatively, you can choose whichever editor you are most comfortable for work
 - [Visual Studio Code](https://code.visualstudio.com/)
 - [Go extension](https://marketplace.visualstudio.com/items?itemName=golang.go)
 
+> 📝 **Tip** - If your are using GitHub Codespaces or Dev Containers, the Go extension is already installed for you. You find more details on these options in the [Repository Prerequisites](../contributing-code-prerequisites/README.md).
+
 Install both of these and then follow the steps in the *Quick Start* for the Go extension.
 
 The extension will walk you through an automated install of some additional tools that match your installed version of Go.
@@ -23,16 +25,16 @@ The extension will walk you through an automated install of some additional tool
 
 At this point you should be able to open any of the Go files in the repo and see syntax highlighting working.
 
-**Launching VSCode**
+## Launching VS Code
 
-The best way to launch VS Code for Go is to do *File* -> *Open Folder* on the repository. 
+The best way to launch VS Code for Go is to do *File* -> *Open Folder* on the repository.
 
 You can easily do this from the command shell with `code .`, which opens the current directory as a folder in VS Code.
 
-
 ## Next step
+
 - [Build Radius](first-commit-02-building.md)
 
 ## Related links
 
-- [Go in Visual Studio Code](https://code.visualstudio.com/docs/languages/go)
+- [Go in Visual Studio Code](https://code.visualstudio.com/docs/languages/go)

docs/contributing/contributing-code/contributing-code-first-commit/first-commit-04-debugging-cli/index.md

@@ -2,67 +2,76 @@
 
 ## Debugging your changes
 
-### Creating debug settings
+The following sections describe the debugging in Visual Studio Code (VS Code). If you are using another editor you can skip the following sections.
 
-You can debug your changes right from VS Code. It requires a small amount of set up for Go.
+>📝 **Tip** The first time you debug on **macOS** with a given version of Go you will be prompted to enter your password. It is normal for this to take 1-2 minutes for the prompt to appear the first time.
 
-First, open the [**Run View**](https://code.visualstudio.com/docs/editor/debugging#_run-view) in VS Code. You can do this either by clicking the icon or using the keyboard shortcut `shift+command+D` (`shift+control+d`) on Windows.
+## Predefined debug configurations
 
-<img width="300px" src="run-view.png" alt="Selecting the run view">
+You can debug your changes right from VS Code. The repository has a `.vscode` directory which contains several launch configurations containing debugging configurations. We describe the configurations in the following sections.
 
-At the top of the new pane you should see something like the following:
+### Debugging rad CLI
 
-<img width="400px" src="options-in-run-view.png" alt="Opens in the run view"><br />
+This section describes the configuration named **"Debug rad CLI"**. This is a basic Go debugger configuration that is set up to launch the `rad` CLI. To try it out, set a breakpoint in `main.go`. Set the breakpoint by clicking in the *gutter* to the left of the line numbers in you editor. Place the breakpoint on the new line you added in `main.go`.
 
-Click on `create a launch.json file`.
+<img src="img/main-with-breakpoint.png" alt="Placing a breakpoint in main.go" width="600" height="auto">
 
+The debugger will stop the program prior to crossing over your breakpoint. Execute the following steps to launch the CLI in the debugger:
 
-This will open the file `.vscode/launch.json` in the editor. This is where VS Code stores information about different debugging configurations.
+- Open the debug pane.
 
-Replace the contents with the following text:
+  <img src="img/vscode-debug-pane.png" alt="VS Code debug pane" width="600" height="auto">
 
-```bash
-{
-    "version": "0.2.0",
-    "configurations": [
-        {
-            "name": "rad CLI",
-            "type": "go",
-            "request": "launch",
-            "mode": "debug",
-            "program": "${workspaceFolder}/cmd/rad/main.go",
-            "cwd": "${workspaceFolder}",
+- Select the **"Debug rad CLI"** entry from the drop down list.
 
-            // If you need to specify command line arguments
-            // for the CLI they go here as a JSON array of strings
-            "args": []
-        }
-    ]
-}
-```
+  <img src="img/vscode-debug-config-selection.png" alt="VS Code debug configuration selection" width="600" height="auto">
 
-> This is a basic Go debugger configuration that is set up to launch the `rad` CLI. You can create definitions for any set of debug settings you want to keep handy.
+- Click the icon with the green triangle to launch the debugging session.
 
-### Running with the debugger
+  <img src="img/vscode-debug-start.png" alt="VS Code start selected debug configuration" width="600" height="auto">
 
-To try it out, first you should set a breakpoint in `main.go`. The debugger will stop the program prior to crossing over your breakpoint.
+Before the debugging will start the project is build in the background. This might take some time. After the build is completed the program will start and the breakpoint should be hit.
 
-Set a breakpoint by clicking in the *gutter* to the left of the line numbers in you editor. Place the breakpoint on the new line you added in `main.go`.
+<img src="img/main-breakpoint-hit.png" alt="Hitting a breakpoint in main.go" width="600" height="auto">
 
-<img width="600px" src="main-with-breakpoint.png" alt="Placing a breakpoint">
+You can play around with the various debugger features, like stepping into code. When you're done, hit the red square *stop* icon in the debugger tools to end the debugging session.
+
+> 📝 **Tip** - You can create definitions for any set of debug settings you want to keep handy.
+
+### Debug rad CLI - prompt for args
+
+This section describes the configuration named **"Debug rad CLI (prompt for args)"**. In contrast to the previous generic one this one uses the specific `rad CLI` commands to kick of the debugger.  
+
+Let us test this setup by checking debugging the `rad version` command. The file is located at `cmd/rad/cmd/version.go`. Set a breakpoint at the beginning of the function `writeVersionString`:
+
+<img src="img/version-with-breakpoint.png" alt="Placing a breakpoint in version.go" width="600" height="auto">
+
+The debugger will stop the program prior to crossing over your breakpoint. Execute the following steps to launch the CLI command in the debugger:
 
-Now you can launch the CLI in the debugger. Press `F5` to launch the debugger. Alternatively, you can click the icon with the green triangle in the *run view* to launch.
+- Open the debug pane.
 
-After some time the program will start and the breakpoint should be hit.
+  <img src="img/vscode-debug-pane.png" alt="VS Code debug pane" width="600" height="auto">
 
->**macOS permissions** <br>
-The first time you debug on macOS with a given version of Go you will be prompted to enter your password. It is normal for this to take 1-2 minutes for the prompt to appear the first time.
+- Select the **"Debug rad CLI (prompt for args)"** entry from the drop down list.
 
-<img width="600px" src="main-breakpoint-hit.png" alt="Hitting a breakpoint">
+  <img src="img/vscode-debug-config-selection-with-args.png" alt="VS Code debug configuration selection with arguments" width="600" height="auto">
+
+- Click the icon with the green triangle to launch the debugging session.
+
+  <img src="img/vscode-debug-start-version-with-args.png" alt="VS Code start selected debug configuration with arguments" width="600" height="auto">
+
+- The system will open up the command palette. Enter the command you want to debug i.e. `version` and confirm.  
+
+  <img src="img/vscode-debug-prompt-cmd.png" alt="VS Code debug command prompt" width="600" height="auto">
+
+Before the debugging will start the project is build in the background. This might take some time. After the build is completed the program will start and the breakpoint should be hit.
+
+<img src="img/version-breakpoint-hit.png" alt="Hitting a breakpoint in version.go" width="600" height="auto">
 
 You can play around with the various debugger features, like stepping into code. When you're done, hit the red square *stop* icon in the debugger tools to end the debugging session.
 
 ## Next step
+
 - [Run tests](../first-commit-05-running-tests/index.md)
 
 ## Related Links