Merge pull request #4599 from microsoft/feature/side-loading-doc

- adds side loading instructions for the vscode extension

.github/workflows/dotnet.yml

@@ -70,6 +70,12 @@ jobs:
       - name: Publish ${{ matrix.os }}
         run: dotnet publish ./src/kiota/kiota.csproj -c Release -p:PublishSingleFile=true -o ./${{ matrix.os }}
 
+      - name: Upload artifact
+        uses: actions/upload-artifact@v4
+        with:
+          name: ${{ matrix.os }}
+          path: ./${{ matrix.os }}
+
       # Mac and Linux
       - name: Isolate the binary
         if: runner.os != 'Windows'

vscode/microsoft-kiota/debugging.md

@@ -1,5 +1,48 @@
 # Debugging the extension
 
-1. run `dotnet publish ./src/kiota/kiota.csproj -p:PublishSingleFile=true -p:PublishReadyToRun=true --self-contained -c Release -r <win-x64|linux-x64|osx-x64> -o ./vscode/microsoft-kiota/.kiotabin/<versionInPackage.json>/<rid>/`
+## Running in debug mode
+
+Context: you're a developer working on the extension, and you want to debug/step through the extension code.
+
+1. run `dotnet publish ./src/kiota/kiota.csproj -p:PublishSingleFile=true -p:PublishReadyToRun=true --self-contained -c Release -r <rid> -o ./vscode/microsoft-kiota/.kiotabin/<kiotaVersionInPackage.json>/<rid>/` where rid is one of `win-x64|linux-x64|osx-x64` and kiotaVersionInPackage is the kiotaVersion field in `vscode/microsoft-kiota/package.json`.
 1. in `vscode/microsoft-kiota` run `code . && npm i`
 1. in the code instance that was opened at step 2, just press f5
+
+## Side loading the extension
+
+Context: you're most likely a program manager eager to demo the latest bits from an active development branch.
+
+### Pre-requisites
+
+- GitHub CLI `winget install GitHub.CLI`
+- dotnet 8 `winget install Microsoft.DotNet.SDK.8`
+- node 20 `winget install CoreyButler.NVMforWindows && nvm install lts && nvm use lts`
+- vsce & TypeScript `npm i -g TypeScript @vscode/vsce`
+
+### Steps
+
+#### Building and side-loading the extension
+
+1. make sure to uninstall any version of the extension, including from remote environments if you're remoting into WSL or a devcontainer, to clear any confusion.
+1. clone this repository if you don't have it locally already `gh repo clone microsoft/kiota && cd kiota`.
+1. switch to the development branch `git switch branchName` (you can find the branch name in the pull request).
+1. cd into the extension directory `cd vscode/microsoft-kiota`.
+1. install dependencies `npm i`.
+1. pack the extension `vsce package`.
+1. side load the extension `code --install-extension pathToVsixThatWasCreatedAtPreviousStep` or use the **Install from VSIX** option from the **...** menu in the extensions pane if you're remoting to WSL/devcontainer.
+
+At this point you have the code extension installed, but it needs the kiota executable to work properly.
+
+> Note: alternatively to building the extension yourself, you can download it from [the pipeline](https://github.com/microsoft/kiota/actions/workflows/build-vscode-extension.yml) by filtering the branch (top right corner) with the pull request branch, selecting the latest run, and downloading the vsix from the artifacts. This will allow you to jump directly to the last step.
+
+#### Building kiota
+
+Refer to step 1 from the "debugging" section. The major difference will be the output path:
+
+`~/.vscode/extensions/ms-graph.kiota-<versionInPackage.json>/.kiotabin/<kiotaVersionInPackage.json>/<rid>/`
+
+Where kiotaVersionInPackage is the kiotaVersion field and versionInPackage is the version field in package.json.
+
+> Note: the **.vscode** segment might change to **.vscode-server** if you're remoting to WSL.
+
+> Note: alternatively to building executable yourself, you can download it from [the pipeline](https://github.com/microsoft/kiota/actions/workflows/dotnet.yml) by filtering the branch (top right corner) with the pull request branch, selecting the latest run, and downloading the right OS version from the artifacts. The only remaining work will be to move the downloaded files to the right path above.