Walkthrough

.vscodeignore

@@ -9,6 +9,7 @@
 !images/**
 !snippets/**
 !assets/icons/**
+!assets/walkthrough/**
 !assets/documentation-webview/**
 !assets/swift-docc-render/**
 !node_modules/@vscode/codicons/**

CHANGELOG.md

@@ -4,7 +4,13 @@
 
 ### Added
 
-- Added Swiftly toolchain management support `.swift-version` files, and integration with the toolchain selection UI ([#1717](https://github.com/swiftlang/vscode-swift/pull/1717)
+- A walkthrough for first time extension users ([#1560](https://github.com/swiftlang/vscode-swift/issues/1560))
+
+## 2.10.0 - 2025-07-28
+
+### Added
+
+- Added Swiftly toolchain management support `.swift-version` files, and integration with the toolchain selection UI ([#1717](https://github.com/swiftlang/vscode-swift/pull/1717))
 - Added code lenses to run suites/tests, configurable with the `swift.showTestCodeLenses` setting ([#1698](https://github.com/swiftlang/vscode-swift/pull/1698))
 - New `swift.excludePathsFromActivation` setting to ignore specified sub-folders from being activated as projects ([#1693](https://github.com/swiftlang/vscode-swift/pull/1693))
 - New `swift.recordTestDuration` setting to disable capturing test durations, which can improve performance of heavy test runs ([#1745](https://github.com/swiftlang/vscode-swift/pull/1745))

assets/walkthrough/createNewProject.md

@@ -0,0 +1,14 @@
+# Create a New Swift Project
+![Create new project](./images/createNewProject.gif)
+
+When you select a project template, you'll be prompted to enter a name for your new project. This will be the name of the folder created in your workspace. You can then choose any location in your workspace, or create a new folder for the project.
+
+# Opening Existing Projects
+
+![Open existing project](./images/openProject.gif)
+
+When you open an existing project with a ``Package.swift`` file the extension will start automatically.
+
+Tip: You can view more information about the toolchain and other configurations being used for the project by hovering over the `{}` icon in the bottom right corner of the status bar.
+
+![Hover over {} to see toolchain info](./images/toolchainInfo.png)

assets/walkthrough/customizeSettings.md

@@ -0,0 +1,19 @@
+# Swift Extension Settings
+
+![Swift Extension Settings](./images/settings.gif)
+
+The Swift Extension contains several settings you can customize. You can filter settings Swift extension settings by searching for `@ext:swiftlang.swift-vscode`.
+
+## Inlay Hints
+
+Some language settings such as those for inlay hints for inferred variable types are turned on by default in VS Code.
+
+![Disable Inlay Hints](./images/disableInlayHints.gif)
+
+You can turn off inlay hints for Swift by adding `[swift]` specific settings to your `settings.json` file:
+
+```
+   "[swift]": {
+        "editor.inlayHints.enabled": "off"
+    },
+```

assets/walkthrough/previewDocs.md

@@ -0,0 +1,6 @@
+# Preview Documentation
+![Preview documentation](./images/previewDocumentation.gif)
+
+You can preview [documentation written using DocC](https://www.swift.org/documentation/docc/) directly in VS Code by using the Preview Swift Documentation button at the top right of an editor, or by invoking `Swift: Preview Documentation` in the command palette in a `.docc` bundle.
+
+Note: This feature requires Swift 6.2 or later.

assets/walkthrough/runExecutable.md

@@ -0,0 +1,16 @@
+# Run Swift Executables
+![Runing a swift executable](./images/runExecutable.gif)
+
+You can build and run a Swift binary target via the:
+1. `Run` or `Debug` CodeLens that appears in the `.swift` file that contains your program's entry point
+2. `Project Panel` in the bottom left hand corner of the sidebar under the `Targets` and `Tasks` groups
+3. `Tasks` command: You can configure the build tasks through the `launch.json` file in the `.vscode` folder for the project and then select the target you'd like to build with the `Tasks: Run Task` command from the `Command Pallete`
+4. `Run Swift executable` editor action in the top right corner of the editor
+![Run Swift executable](./images/runSwiftExecutable.png)
+
+
+# Debug Swift Executables
+
+![Debuging a swift executable](./images/debugExecutable.gif)
+
+The extension automatically generates the debug and release variants of launch configurations in `launch.json`. You can debug a target by setting a breakpoint and clicking the the `Debug Swift Executable` editor action or through the `Run and Debug` panel in the sidebar.

assets/walkthrough/runTests.md

@@ -0,0 +1,7 @@
+# Run Swift Testing and XCTest Tests
+![Run a test](./images/runTests.gif)
+
+Swift Testing and XCTests tests are detected automatically. You can run tests by:
+1. Clicking the ▶ button or right clicking ▶ button beside the line number, and selecting a test variant such as `Debug Test` or `Run with Coverage`
+2. Clicking `Run`, `Debug` or `Run w/ Coverage` in the CodeLens
+3. Using the `Test Explorer` in the sidebar

assets/walkthrough/swiftCommands.md

@@ -0,0 +1,7 @@
+# Swift Commands
+
+![Swift Commands](./images/swiftCommands.svg)
+
+Documentation for commands supported by this extension is available on [swift.org](https://docs.swift.org/vscode/documentation/userdocs/commands/).
+
+If you don't find the command you're looking for you can [open a new issue](https://github.com/swiftlang/vscode-swift/issues) or [pull request](https://github.com/swiftlang/vscode-swift/pulls).

assets/walkthrough/swiftToolchains.md

@@ -0,0 +1,10 @@
+The Swift extension automatically detects your installed Swift toolchain. However, it also provides a command called `Swift: Select Toolchain...` which can be used to select between toolchains if you have multiple installed.
+
+You may be prompted to select where to configure this new path. Your options are to:
+
+- `Save it in User Settings`
+- `Save it in Workspace Settings`
+
+Keep in mind that Workspace Settings take precedence over `User Settings`.
+
+The Swift extension will then prompt you to reload the extension in order to pick up the new toolchain. The extension will not use the new toolchain until the extension is restarted.

assets/walkthrough/welcome.md

@@ -0,0 +1,3 @@
+<p align="center">
+    <img src="./images/swiftLogo.svg" width="300" height="300" alt="Welcome" />
+</p>