Updates the CONTRIBUTING.md file

Author: maryamariyan

CONTRIBUTING.md

@@ -1,51 +1,112 @@
-## Local development
+## Table of Contents
 
-### Pre-requisites
+- [Setting Up Local Development Environment](#setting-up-local-development-environment)
+  - [Prerequisites for Development](#prerequisites-for-development)
+  - [Building, Running, and Testing the Repository](#building-running-and-testing-the-repository)
+  - [Setting Up Local Language Servers](#setting-up-local-language-servers)
+    - [Roslyn](#roslyn)
+    - [Razor](#razor)
+  - [Debugging Local Language Servers](#debugging-local-language-servers)
+    - [Roslyn](#roslyn-1)
+    - [Razor](#razor-1)
+  - [Creating VSIX Packages for the Extension](#creating-vsix-packages-for-the-extension)
+- [Updating the `Roslyn` Language Server Version](#updating-the-roslyn-language-server-version)
 
-First install:
+## Setting Up Local Development Environment
+
+Setting up your local development environment for the vscode-csharp repository involves several steps. This guide will walk you through the process.
+
+### Prerequisites for Development
+
+Before you start, make sure you have the following software installed on your machine:
 
 * Node.js ([v18.17.0 LTS](https://nodejs.org/en/blog/release/v18.17.0) is recommended).
 * Npm (The version shipped with node is fine)
-* .NET 7.0 SDK (dotnet should be on your path)
+* .NET 8.0 SDK (dotnet should be on your path)
+
+Once you have these installed, you can proceed to clone the vscode-csharp repository:
+
+```bash
+git clone https://github.com/your-username/vscode-csharp.git
+cd vscode-csharp
+```
+
+Next, install the necessary npm packages:
+
+```bash
+npm install
+```
+
+Now, you're ready to start building, running, and testing the repository.
+
+### Building, Running, and Testing the Repository
+
+Follow these steps to build, run, and test the repository:
+
+#### Building
+
+1. Run `npm i` - This command installs the project dependencies.
+2. Run `npm i -g gulp` - This command installs Gulp globally.
+3. Run `gulp installDependencies` - This command downloads the various dependencies as specified by the version in the [package.json](package.json) file.
+4. Run `code .` - This command opens the project in Visual Studio Code.
+5. Run `npm run watch` (Optional) - This command watches for code changes.
+
+#### Running
+
+After completing the build steps:
+
+1. Press <kbd>Ctrl+Shift+D</kbd> to open the Run view in VS Code and ensure `Launch Extension` is selected.
+2. Start debugging by pressing <kbd>F5</kbd>.
+
+#### Testing
+
+To run tests:
+
+1. Execute `npm run test` or press <kbd>F5</kbd> in VS Code with the "Launch Tests" debug configuration selected.
+2. For integration tests, select `Razor Integration Tests` and press <kbd>F5</kbd> to start debugging.
 
-### Build and run the extension
+### Setting Up Local Language Servers
 
-To run and develop the extension do the following:
+This section provides a step-by-step guide on setting up locally developed Razor or Roslyn language servers for debugging. This setup is beneficial when troubleshooting the behavior of these language servers with the VSCode C# extension.
 
-* Run `npm i`
-* Run `npm i -g gulp`
-* Run `gulp installDependencies` (this will download the various dependencies as specified by the version in the [package.json](package.json))
-* Open in Visual Studio Code (`code .`)
-* _Optional:_ run `npm run watch`, make code changes
-* Press <kbd>F5</kbd> to debug
+#### Roslyn
 
-To **test** do the following: `npm run test` or <kbd>F5</kbd> in VS Code with the "Launch Tests" debug configuration.
+1. Clone the [Roslyn repository](https://github.com/dotnet/roslyn) locally. This repository contains the Roslyn server implementation.
+2. Follow the build instructions provided in the repository.
 
-### Using a locally developed Roslyn server
+After building, you can find the server DLL in the build output directory. The typical location is `$roslynRepoRoot/artifacts/bin/Microsoft.CodeAnalysis.LanguageServer/Debug/net8.0/Microsoft.CodeAnalysis.LanguageServer.dll`, but this may vary based on the built configuration.
 
-https://github.com/dotnet/roslyn contains the server implementation.  Follow the instructions there to build the repo as normal.  Once built, the server DLL will be located in the build output directory, typically
+#### Razor
 
-`$roslynRepoRoot/artifacts/bin/Microsoft.CodeAnalysis.LanguageServer/Debug/net7.0/Microsoft.CodeAnalysis.LanguageServer.dll`
+1. Clone the [Razor repository](https://github.com/dotnet/razor) locally. This repository contains the Razor server implementation.
+2. Follow the build instructions provided in the repository.
 
-depending on which configuration is built.  Then, launch the extension here and change the VSCode setting `dotnet.server.path` to point to the Roslyn dll path you built above and restart the language server.
+Similar to Roslyn, after building, the server DLL will be in the build output directory. The typical location is `$razorRepoRoot/artifacts/bin/rzls/Debug/net8.0`, but this may vary based on the built configuration.
 
-If you need to debug the server, you can set the VSCode setting `dotnet.server.waitForDebugger` to true.  This will trigger a `Debugger.Launch()` on the server side as it starts.
+### Debugging Local Language Servers
 
-### Using a locally developed Razor server
+This section provides instructions on how to debug locally developed Roslyn and Razor language servers.
 
-https://github.com/dotnet/razor contains the server implementation.  Follow the instructions there to build the repo as normal.  Once built, the server will be located in the build output directory, typically
+#### Roslyn
 
-`$razorRepoRoot/artifacts/bin/rzls/Debug/net7.0`
+1. Open the VSCode settings by using the shortcut `Ctrl+,`.
+2. Enter `dotnet server` in the search box to display Roslyn-related settings.
+3. Update the `dotnet.server.path` setting to the path of the Roslyn DLL you built earlier, then restart the language server.
+4. If you need to debug the server, enable the `dotnet.server.waitForDebugger` setting. This action triggers a `Debugger.Launch()` on the server side when it starts.
 
-depending on which configuration is built.  Then, launch the extension here and change the VSCode setting `razor.languageServer.directory` to point to the Razor executable path you built above and reload the window.
+#### Razor
 
-If you need to debug the server, you can set the VSCode setting `razor.languageServer.debug` to true.  This will trigger a `Debugger.Launch()` on the server side as it starts. You can also set `razor.server.trace` to `Debug` to get more log messages in the output window
+1. Open the VSCode settings by using the shortcut `Ctrl+,`.
+2. Enter `Razor` in the search box to display Razor-related settings.
+3. Update the `razor.languageServer.directory` setting to the path of the Razor DLL you built earlier, then restart the language server.
+4. If you need to debug the server, enable the `razor.languageServer.debug` setting. This action triggers a `Debugger.Launch()` on the server side when it starts.
+5. For more detailed log messages in the output window, set `razor.server.trace` to `Debug`.
 
-### Creating VSIXs
+### Creating VSIX Packages for the Extension
 
-VSIXs can be created using the gulp command `gulp vsix:release:package`.  This will create all the platform specific VSIXs that you can then install manually in VSCode.
+To package this extension, we need to create VSIX Packages. The VSIX packages can be created using the gulp command `gulp vsix:release:package`. This will create all the platform specific VSIXs that you can then install manually in VSCode.
 
-## Updating the Roslyn server version
+## Updating the `Roslyn` Language Server Version
 
 To update the version of the roslyn server used by the extension do the following:
 1.  Find the the Roslyn signed build you want from [here](https://dnceng.visualstudio.com/internal/_build?definitionId=327&_a=summary).  Typically the latest successful build of main is fine.