Walkthrough #1709

rbenegal · 2025-07-10T12:51:10Z

Description

Add some GIFs and additional steps for running, debugging and DocC previewing to the walkthrough created by @plemarquand.

Issue: 1560

Tasks

Required tests have been written
Documentation has been updated
Added an entry to CHANGELOG.md if applicable

Adds a walkthrough to the package.json that guides users through: - Installing Swift - Creating a New Project - Extension Commands - Running Tests - Selecting a Toolchain

Add some GIFs and additional steps for running, debugging and DocC previewing. Issue: swiftlang#1560

award999

Some suggestions, I now realize that the buttons are provided in the package.json, not the markdown files so I see you have a lot of the buttons I was suggesting :)

Thanks for doing this, looking great

award999 · 2025-07-17T15:11:19Z

assets/walkthrough/createNewProject.md

+
+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 status bar.


maybe worth adding an image to make sure they know which status item you're talking about

award999 · 2025-07-17T15:14:15Z

assets/walkthrough/createNewProject.md

+
+![Open existing project](./images/openProject.gif)
+
+When you open an existing project with a ``Package.swift`` file the extension will start automatically.


I wonder if open could be its own walkthrough where you could show the explorer with Package.swift in it and the swift package resolve task getting kicked off. Sort of visual image to know it's working.

If we split that to a separate walkthrough, could mention the prompt to open in new window OR add to workspace as a way to link to the multi-root workspace documentation for vscode.

award999 · 2025-07-17T15:15:24Z

assets/walkthrough/customizeSettings.md

+
+![Swift Extension Settings](./images/settings.gif)
+
+The Swift Extension contains several settings you can customize. 


Maybe mention they can filter settings by @ext:swiftlang.swift-vscode

award999 · 2025-07-17T15:17:03Z

assets/walkthrough/previewDocs.md

+# Preview Documentation
+![Preview documentation](./images/previewDocumentation.gif)
+
+You can preview [documentation written using DocC](https://www.swift.org/documentation/docc/) directly in VS Code.


mention how they get to this point, which file extensions can be open, is there a palette or context command to load the preview?

award999 · 2025-07-17T15:18:00Z

assets/walkthrough/runExecutable.md

+![Run swift executable](./images/runExecutable.gif)
+
+You can run a Swift binary target via the:
+1. Code lens that appears in the `.swift` file 


Suggested change

1. Code lens that appears in the `.swift` file

1. CodeLens that appears in the `.swift` file

this is the normal spelling I think

maybe image too?

award999 · 2025-07-17T15:27:01Z

assets/walkthrough/runExecutable.md

+2. Project Panel in the bottom left hand corner of the sidebar
+3. Tasks command: You can configure the build tasks through the `launch.json` file in the `.vscode` folder for the project
+
+![Debug Swift Executable](./images/debugExecutable.gif)


worth noting that the extension automatically generates the debug and release variant launch configurations that they can modify, maybe even having an action button to open the launch.json

award999 · 2025-07-17T15:27:28Z

assets/walkthrough/runTests.md

+# Run Swift Testing and XCTest Tests
+![Run a test](./images/runTests.gif)
+
+XCTests and Swift Testing tests are detected automatically. You can run them by clicking the ▶ button, with the `Run Test` code lens or through the `Test Explorer` in the sidebar.


code lens -> CodeLens

don't need to call out every type but showing the run with code coverage one too may be nice...

award999 · 2025-07-17T15:28:48Z

assets/walkthrough/runningTests.md

@@ -0,0 +1 @@
+![Testing](./images/testing.png)


dupe of assets/walkthrough/runTests.md?

award999 · 2025-07-17T15:30:14Z

assets/walkthrough/swiftCommands.md

+# Swift Commands
+
+![Swift Commands](./images/swiftCommands.svg)
+


Maybe have a command button that opens command palette with "Swift:" set as the filter. And then document that cmd+shift+p opens command palette, and filter by "Swift:" to see all the swift commands that the extension provides.

award999 · 2025-07-17T15:30:58Z

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.


can we add action button to the Swift: Select Toolchain... command

plemarquand and others added 5 commits July 10, 2025 08:47

Add an extension walkthrough

8cbd9e1

Adds a walkthrough to the package.json that guides users through: - Installing Swift - Creating a New Project - Extension Commands - Running Tests - Selecting a Toolchain

Ensure assets are added to .vsix

8ac5cc3

Properly theme swiftCommands.svg

fc565dd

Fixup wording

09b18d9

Update the walkthrough

a0614ec

Add some GIFs and additional steps for running, debugging and DocC previewing. Issue: swiftlang#1560

rbenegal requested review from adam-fowler, 0xTim and award999 as code owners July 10, 2025 12:51

rbenegal marked this pull request as draft July 10, 2025 12:51

rbenegal requested review from plemarquand, tracymiranda and matthewbastien July 10, 2025 12:51

rbenegal marked this pull request as ready for review July 17, 2025 14:30

award999 reviewed Jul 17, 2025

View reviewed changes

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

Walkthrough #1709

Walkthrough #1709

rbenegal commented Jul 10, 2025 •

edited

Loading

Uh oh!

award999 left a comment

Uh oh!

award999 Jul 17, 2025

Uh oh!

award999 Jul 17, 2025

Uh oh!

award999 Jul 17, 2025

Uh oh!

award999 Jul 17, 2025

Uh oh!

award999 Jul 17, 2025

Uh oh!

award999 Jul 17, 2025

Uh oh!

award999 Jul 17, 2025

Uh oh!

award999 Jul 17, 2025

Uh oh!

award999 Jul 17, 2025

Uh oh!

award999 Jul 17, 2025

Uh oh!

award999 Jul 17, 2025

Uh oh!

award999 Jul 17, 2025

Uh oh!

Uh oh!


		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 status bar.


		![Open existing project](./images/openProject.gif)

		When you open an existing project with a ``Package.swift`` file the extension will start automatically.


		![Swift Extension Settings](./images/settings.gif)

		The Swift Extension contains several settings you can customize.

	1. Code lens that appears in the `.swift` file
	1. CodeLens that appears in the `.swift` file

		# Swift Commands

		![Swift Commands](./images/swiftCommands.svg)

		@@ -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.

		@@ -0,0 +1 @@
		![Testing](./images/testing.png)

Walkthrough #1709

Are you sure you want to change the base?

Walkthrough #1709

Conversation

rbenegal commented Jul 10, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Description

Tasks

Uh oh!

award999 left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

rbenegal commented Jul 10, 2025 •

edited

Loading