Update the Buildx debug documentation

CHANGELOG.md

@@ -23,6 +23,10 @@ All notable changes to the Docker DX extension will be documented in this file.
     - return document links for files referenced in the short-form `volumes` attribute of a service object ([docker/docker-language-server#460](https://github.com/docker/docker-language-server/issues/460))
     - return document links for files referenced in the long-form `volumes` attribute of a service object that has a bind mount ([docker/docker-language-server#462](https://github.com/docker/docker-language-server/issues/462))
 
+### Removed
+
+- the experimental `docker.extension.enableBuildDebugging` setting has been removed and the build debugging features are now enabled by default
+
 ## [0.16.0] - 2025-08-26
 
 ### Added

DEBUGGING.md

@@ -1,21 +1,15 @@
 # Build Debugging
 
-> ⚠️ This feature is under **active** development and there may be breaking changes as we continue experimenting and fine tuning it. If you have feedback about this feature, please [open an issue](https://github.com/docker/vscode-extension/issues) or [start a discussion thread](https://github.com/docker/vscode-extension/discussions) and let us know what you think.
-
 ## Overview
 
-Buildx provides an implementation of the [Debug Adapter Protocol](https://microsoft.github.io/debug-adapter-protocol/). This means development tools that support and implement the protocol can interface with Buildx directly and step through the build process in real-time.
+[Buildx](https://github.com/docker/buildx) provides an implementation of the [Debug Adapter Protocol](https://microsoft.github.io/debug-adapter-protocol/). This means development tools that support and implement the Debug Adapter Protocol can interface with Buildx directly and step through its build process in real-time.
 
 ## Requirements
 
 To use the build debugging feature, you will need to have [Buildx](https://github.com/docker/buildx) installed. The minimum supported version is v0.28. You can get Buildx v0.28 by [installing Docker Desktop](https://docs.docker.com/install/) 4.46 or by [installing Buildx manually](https://github.com/docker/buildx?tab=readme-ov-file#manual-download).
 
 1. Run `docker buildx version` to check your Buildx version.
 2. Run `BUILDX_EXPERIMENTAL=1 docker buildx dap` to check that the `dap` subcommand is available in your Buildx installation.
-3. Search for "docker enable build debugging" in the VS Code settings (<kbd>Ctrl+,</kbd> or <kbd>Command+,</kbd>) and enable the experimental "Enable Build Debugging" setting.
-4. Restart VS Code for the setting to take effect.
-
-![Use the settings page to enable the build debugging feature](resources/debugging/settings.png)
 
 ## Features
 
@@ -88,4 +82,6 @@ The Variables pane in Visual Studio Code lets you view the value of `ARG` and `E
 
 If you encounter errors or issues with this feature, the DAP logs may help. Open the Output panel and select "Docker Buildx DAP" from the drop down.
 
-![The opened terminal can be interfaced with for debugging in real-time](resources/debugging/dap-logs.png)
+![DAP log messages can be viewed in the Output panel](resources/debugging/dap-logs.png)
+
+If it is unclear what is wrong, please do not hesitate to [open an issue](https://github.com/docker/vscode-extension/issues) or [start a discussion thread](https://github.com/docker/vscode-extension/discussions).

README.md

@@ -56,9 +56,9 @@ The extension provides inline suggestions to generate a Bake target to correspon
 
 ![Suggesting Bake targets based on the content of the local Dockerfile](resources/readme/docker-bake-inline-completion.png)
 
-### Build Debugging (EXPERIMENTAL)
+### Build Debugging
 
-This feature is under active development and requires version `v0.26.1` of `docker buildx` or newer. This is disabled by default. Open [DEBUGGING.md](./DEBUGGING.md) to learn more about this feature in Visual Studio Code and how to enable it.
+Dockerfile builds can be stepped through in debug mode with the Debug Adapter Protocol implementation in Buildx. Open [DEBUGGING.md](./DEBUGGING.md) to learn about this feature and what its requirements are.
 
 For information about Buildx and the Debug Adapter Protocol, go [here](https://github.com/docker/buildx/blob/master/docs/dap.md). If you have any bugs, feature requests, or feedback about Buildx's support for Debug Adapter Protocol, please report them [here](https://github.com/docker/buildx/issues/new/choose).
 

package.json

@@ -143,15 +143,6 @@
     "configuration": {
       "title": "Docker DX",
       "properties": {
-        "docker.extension.enableBuildDebugging": {
-          "type": "boolean",
-          "description": "Enables build debugging features from the Docker DX extension. This feature is under active development. Note that changing this value requires a restart of Visual Studio Code to take effect.",
-          "markdownDescription": "Enable build debugging features from the Docker DX extension. This feature is under active development. Note that changing this value requires a **restart** of Visual Studio Code to take effect.",
-          "default": false,
-          "tags": [
-            "experimental"
-          ]
-        },
         "docker.extension.enableComposeLanguageServer": {
           "type": "boolean",
           "description": "Enable Compose editing features from the Docker DX extension. Note that changing this value requires a restart of Visual Studio Code to take effect.",

src/dap/config.ts

@@ -105,31 +105,6 @@ class DockerfileDebugAdapterTracker implements vscode.DebugAdapterTracker {
 }
 
 export function setupDebugging(ctx: vscode.ExtensionContext) {
-  if (!getExtensionSetting<boolean>('enableBuildDebugging')) {
-    // the command is still contributed to the Command Palette because of package.json
-    registerCommand(ctx, DebugEditorContentsCommandId, async () => {
-      vscode.window.showErrorMessage(
-        'Build Debugging for Docker is an experimental feature that is under active development. ' +
-          'Enable the feature by toggling the docker.extension.enableBuildDebugging setting to true and restarting your client.',
-      );
-      return Promise.resolve(false);
-    });
-
-    // the debugger is still contributed and technically registered because of package.json
-    ctx.subscriptions.push(
-      vscode.debug.registerDebugConfigurationProvider('dockerfile', {
-        resolveDebugConfiguration(): vscode.ProviderResult<vscode.DebugConfiguration> {
-          vscode.window.showErrorMessage(
-            'Build Debugging for Docker is an experimental feature that is under active development. ' +
-              'Enable the feature by toggling the docker.extension.enableBuildDebugging setting to true and restarting your client.',
-          );
-          return undefined;
-        },
-      }),
-    );
-    return;
-  }
-
   let channel = vscode.window.createOutputChannel('Docker Buildx DAP', 'log');
 
   registerCommand(

src/utils/settings.ts

@@ -2,8 +2,7 @@ import * as vscode from 'vscode';
 
 type DockerExtensionSettings =
   | 'dockerEngineAvailabilityPrompt'
-  | 'enableComposeLanguageServer'
-  | 'enableBuildDebugging';
+  | 'enableComposeLanguageServer';
 
 /**
  * Retrieves the value of a specified setting from the Docker extension's configuration.