docs: update debug guide

Signed-off-by: Christian Lechner <[email protected]>

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`.
+![Placing a breakpoint in main.go](img/main-with-breakpoint.png)
 
+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:
+![VS Code debug pane](img/vscode-debug-pane.png)
 
-```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": []
-        }
-    ]
-}
-```
+![VS Code debug configuration selection](img/vscode-debug-config-selection.png)
 
-> 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
+![VS Code start selected debug configuration](img/vscode-debug-start.png)
 
-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`.
+![Hitting a breakpoint in main.go](img/main-breakpoint-hit.png)
 
-<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`:
+
+![Placing a breakpoint in version.go](img/version-with-breakpoint.png)
+
+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.
+![VS Code debug pane](img/vscode-debug-pane.png)
 
->**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">
+![VS Code debug configuration selection with arguments](img/vscode-debug-config-selection-with-args.png)
+
+- Click the icon with the green triangle to launch the debugging session.
+
+![VS Code start selected debug configuration with arguments](img/vscode-debug-start-version-with-args.png)
+
+- The system will open up the command palette. Enter the command you want to debug i.e. `version` and confirm.  
+
+![VS Code debug command prompt](img/vscode-debug-prompt-cmd.png)
+
+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.
+
+![Hitting a breakpoint in version.go](img/version-breakpoint-hit.png)
 
 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

docs/contributing/contributing-code/contributing-code-prerequisites/README.md

@@ -39,7 +39,7 @@ The best way to launch VS Code for Go is to do *File* -> *Open Folder* on the re
 
 You can easily do this from the command shell with `code .`, which opens the current directory as a folder in VS Code.
 
-## Tool Overview
+## Tool overview
 
 Contributing to Project Radius requires several tools to get started. This section lists them grouped by their context
 
@@ -49,7 +49,7 @@ Contributing to Project Radius requires several tools to get started. This secti
     Note: some of this content is synchronized with the first-commit guide for simplicity. Keep these in sync!
 -->
 
-### Required Tools
+### Required tools
 
 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:
 
@@ -63,7 +63,7 @@ This is the list of core dependencies to install for the most common tasks. In g
 
 To build our containers, you also need [Docker](https://docs.docker.com/engine/install/).  
 
-### Additional Tools
+### Additional tools
 
 The following tools are required depending on the task at hand.
 
@@ -75,7 +75,7 @@ The easiest way to run Radius is on Kubernetes. To do this you will need the abi
 - [Install Helm](https://helm.sh/docs/intro/install/)
 - [Install Kind](https://kubernetes.io/docs/tasks/tools/#kind)
 
-#### Troubleshooting Kubernetes
+#### Troubleshooting kubernetes
 
 You might want tools that can help debug Kubernetes problems and understand what's going on in the cluster. Here are some recommendations from the team:
 
@@ -95,7 +95,7 @@ The default `go test` output can be hard to read when you have many tests. We re
 
 - [gotestsum](https://github.com/gotestyourself/gotestsum#install)
 
-## Development Environment - Setup Options
+## Development environment - setup options
 
 The following sections describe the aforementioned alternatives of development setups in more detail.
 
@@ -108,7 +108,7 @@ The steps to execute are:
 1. Press this button[![Open in GitHub Codespaces](https://github.com/codespaces/badge.svg)](https://github.com/codespaces/new?hide_repo_select=true&ref=main&repo=340522752&skip_quickstart=true&machine=basicLinux32gb&devcontainer_path=.devcontainer%2Fcontributor%2Fdevcontainer.json&geo=UsWest)
 1. There is no second step - you are ready to contribute 😎
 
-> **Note** - When using GitHub Codespoces cost can occur on your side after you have used up the monthly included storage and core hours for your account. You find more details [here](https://docs.github.com/en/billing/managing-billing-for-github-codespaces/about-billing-for-github-codespaces).
+> **Note** - When using GitHub Codespaces cost can occur on your side after you have used up the monthly included storage and core hours for your account. You find more details [here](https://docs.github.com/en/billing/managing-billing-for-github-codespaces/about-billing-for-github-codespaces).
 
 ### VS Code and Dev Container
 
@@ -136,7 +136,7 @@ Once the container is up and running you can start with your contribution.
 
 > 📝 **Tip** - You find more information about developing inside a container [here](https://code.visualstudio.com/docs/devcontainers/containers)
 
-### Local Installation
+### Local installation
 
 to have all prerequisites installed locally you must install the tools mentioned in the sections [Tool Overview - Required Tools](#required-tools) and [Tool Overview - Additional Tools](#additional-tools) on your local machine.
 
@@ -161,7 +161,7 @@ Using Homebrew:
 brew install make
 ```
 
-## Testing Required Tools
+## Testing required tools
 
 Independent of the setup option you have chosen, you can now test your tooling. If not already done, navigate to the cloned project in your command shell and build the main outputs using `make`:
 
@@ -171,7 +171,7 @@ make build && make lint
 
 Running these steps will run our build and lint steps and verify that the tools are installed correctly. If you get stuck or suspect something is not working in these instructions please [open an issue](https://github.com/radius-project/radius/issues/new/choose).
 
-### Code Generation
+### Code generation
 
 Our code generation targets are used to update generated OpenAPI specs and generated Go code based on those OpenAPI specs. Additionally, some Go code is generated mocks or Kubernetes API types.