[release] prepare v0.41.3 release

d0d95ab extension/CHANGELOG.md: add a note for v0.41.3
b501de3 Revert "docs: update the debugging doc about remote mode default adapter"
9330b08 extension/src/goTelemetry: do our JSON enc/dec for telemetry start time
f8173bc extension/src/welcome: fix 'go.showWelcome' setting interpretation
ad37a53 Revert "src/goDebugConfiguration: change remote/attach default to dlv-dap"
40990c0 extension: resolve variables in customFormatter field.
78deb71 docs: fix tools information doc link

Change-Id: Ia32f0b7babc681365a02f5fd99b25573fb7934ab

Author: hyangah

docs/debugging-legacy.md

@@ -2,7 +2,7 @@
 
 The Go extension historically used a small adapter program to work with the Go debugger, [Delve].
 The extension transitioned to communicate with [Delve] directly but there are still cases you may
-need to use the legacy debug adapter. This document explains how to use the
+need to use the legacy debug adapter (e.g. remote debugging). This document explains how to use the
 ***legacy*** debug adapter.
 
 
@@ -45,6 +45,8 @@ To opt in to use the legacy debug adapter (`legacy`) by default, add the followi
 ```
 
 If you want to use the legacy mode for only a subset of your launch configurations, you can use [the `debugAdapter` attribute](#launchjson-attributes) to switch between `"dlv-dap"` and `"legacy"` mode.
+For [Remote Debugging](#remote-debugging) (launch configuration with `"mode": "remote"` attribute),
+the extension will use the `"legacy"` mode by default, so setting this attribute won't be necessary.
 
 Throughout this document, we assume that you opted in to use the legacy debug adapter.
 For debugging using the new debug adapter (default, `"dlv-dap"` mode), please see the documentation about [Debugging](https://github.com/golang/vscode-go/tree/master/docs/debugging-legacy.md).

docs/debugging.md

@@ -6,8 +6,26 @@ activities using
 [VS Code’s Debugging UI](https://code.visualstudio.com/docs/editor/debugging).
 
 These debugging features are possible by using
-[Delve](https://github.com/go-delve/delve), the Go debugger, and its
-[native debug adapter implementation](https://github.com/go-delve/delve/tree/master/service/dap).
+[Delve](https://github.com/go-delve/delve), the Go debugger.
+
+Previously, the Go extension communicated with Delve through a custom debug
+adaptor program (`legacy` mode). Since
+[`Delve`'s native debug adapter implementation](https://github.com/go-delve/delve/tree/master/service/dap)
+is available, the Go extension is transitioning to deprecate the legacy debug
+adapter in favor of direct communication with Delve via
+[DAP](https://microsoft.github.io/debug-adapter-protocol/overview).
+
+
+ 📣 **We are happy to announce that the new _`dlv-dap`_ mode of Delve
+ integration is enabled for _local_ _debugging_ by default. For
+ [_remote_ _debugging_](#remote-debugging) it is the default in
+ [Go Nightly](nightly.md) and is available with stable builds on demand with
+ `"debugAdapter": "dlv-dap"` attribute in `launch.json` or `settings.json`!**
+
+Many features and settings described in this document may be available only with
+the new `dlv-dap` mode. For troubleshooting and configuring the legacy debug
+adapter, see
+[the legacy debug adapter documentation](https://github.com/golang/vscode-go/tree/master/docs/debugging-legacy.md).
 
 ## Get started
 
@@ -64,9 +82,7 @@ from the tree head.
 
 ### Switch to legacy debug adapter
 
-Previously, the Go extension communicated with Delve through a custom debug
-adaptor program (aka `legacy` mode). This legacy adapter is no longer maintained
-and will be removed by the end of 2024 H2.
+Note: The extension still uses the legacy debug adapter for remote debugging.
 
 If you need to use the legacy debug adapter for local debugging (`legacy` mode)
 by default, add the following in your VSCode settings.
@@ -77,6 +93,9 @@ by default, add the following in your VSCode settings.
     }
 ```
 
+When `mode` is set to `remote` you must explicitly set `debugAdapter` to
+`dlv-dap` to override the legacy adapter default.
+
 If you want to switch to `legacy` for only a subset of your launch
 configurations, you can use
 [the `debugAdapter` attribute](#launchjson-attributes) to switch between
@@ -790,8 +809,8 @@ with a running target.
 
 The
 [headless dlv server](https://github.com/go-delve/delve/tree/master/Documentation/api)
-can now be used with both `"debugAdapter": "dlv-dap"` (default) and
-`"debugAdapter": "legacy"` (with Delve v1.7.3 or newer) as well as Delve's
+can now be used with both `"debugAdapter": "legacy"` (default value) and
+`"debugAdapter": "dlv-dap"` (with Delve v1.7.3 or newer) as well as Delve's
 [command-line interface](https://github.com/go-delve/delve/tree/master/Documentation/cli)
 via `dlv connect`. The `--accept-multiclient` flag makes this a multi-use server
 that persists on `Disconnect` from a client and allows repeated connections from
@@ -818,6 +837,7 @@ Connect to it with a remote attach configuration in your `launch.json`:
 {
     "name": "Connect to external session",
     "type": "go",
+    "debugAdapter": "dlv-dap", // `legacy` by default
     "request": "attach",
     "mode": "remote",
     "port": 12345,

docs/tools.md

@@ -2,7 +2,7 @@
 
 This document describes the tools that power the VS Code Go extension.
 
-Tools will be installed by default when you install the extension. You can also manually install or update all of these tools by running the [`Go: Install/Update Tools`](commands.md#go-installupdate-tools) command. The extension uses pinned versions of command-line tools. See the pinned versions in tools information [here](https://github.com/golang/vscode-go/blob/master/src/goToolsInformation.ts). If any tools are missing, you will see an `Analysis Tools Missing` warning in the bottom-right corner of the editor, which will prompt you to install these tools.
+Tools will be installed by default when you install the extension. You can also manually install or update all of these tools by running the [`Go: Install/Update Tools`](commands.md#go-installupdate-tools) command. The extension uses pinned versions of command-line tools. See the pinned versions in tools information [here](https://github.com/golang/vscode-go/blob/master/extension/src/goToolsInformation.ts). If any tools are missing, you will see an `Analysis Tools Missing` warning in the bottom-right corner of the editor, which will prompt you to install these tools.
 
 VS Code Go will install the tools to your `$GOPATH/bin` by default. 
 

extension/CHANGELOG.md

@@ -1,3 +1,41 @@
+## v0.41.3 - 22 Apr, 2024
+
+This point release temporarily reverts the default remote debugging behavior to
+use the legacy debug adapter due to existing feature gaps.
+Once these gaps are addressed as outlined in
+[Issue 3096](https://github.com/golang/vscode-go/issues/3096),
+we plan to switch the default back to use Delve DAP for remote deubgging.
+
+If you want to continue using [Delve DAP for remote debugging](https://github.com/golang/vscode-go/wiki/debugging#connect-to-headless-delve-with-target-specified-at-server-start-up), use the following
+settings in your `launch.json`.
+
+```json
+{
+    "name": "Debug Remote",
+    "type": "go",
+    "request": "attach",
+    "mode": "remote",
+    "debugAdapter": "dlv-dap", // Use Delve DAP
+    ...
+}
+```
+
+See the full
+[commit history](https://github.com/golang/vscode-go/compare/v0.41.2...v0.41.3)
+for detailed changes.
+
+### Fixes
+- Fixed to substitute variables used in `go.alternateTools` setting's
+  `customFormatter` entry ([Issue 2582](https://github.com/golang/vscode-go/issues/2582)).
+- Corrected handling of `go.showWelcome` setting
+  ([Issue 3319](https://github.com/golang/vscode-go/issues/3319)).
+- Addressed Go telemetry prompt issue in the latest Visual Studio Code
+  ([Issue 3312](https://github.com/golang/vscode-go/issues/3312)).
+
+### Thanks
+
+Thanks for your contributions, @uniquefine, @monitor1379, @suzmue, @hyangah!
+
 ## v0.41.2 - 14 Mar, 2024
 
 This release is a point release to increase the prompt rate of Go telemetry

extension/src/goDebugConfiguration.ts

@@ -183,36 +183,25 @@ export class GoDebugConfigurationProvider implements vscode.DebugConfigurationPr
 			}
 		}
 		// If neither launch.json nor settings.json gave us the debugAdapter value, we go with the default
-		// from package.json (dlv-dap).
+		// from package.json (dlv-dap) unless this is remote attach with a stable release.
 		if (!debugConfiguration['debugAdapter']) {
 			debugConfiguration['debugAdapter'] = defaultConfig.debugAdapter.default;
-			if (
-				debugConfiguration.request === 'attach' &&
-				debugConfiguration['mode'] === 'remote' &&
-				!extensionInfo.isPreview
-			) {
+			if (debugConfiguration['mode'] === 'remote' && !extensionInfo.isPreview) {
+				debugConfiguration['debugAdapter'] = 'legacy';
+			}
+		}
+		if (debugConfiguration['debugAdapter'] === 'dlv-dap') {
+			if (debugConfiguration['mode'] === 'remote') {
+				// This needs to use dlv at version 'v1.7.3-0.20211026171155-b48ceec161d5' or later,
+				// but we have no way of detectng that with an external server ahead of time.
+				// If an earlier version is used, the attach will fail with  warning about versions.
+			} else if (debugConfiguration['port']) {
 				this.showWarning(
-					'ignoreDefaultDebugAdapterChangeWarning',
-					"We are using the 'dlv-dap' integration for remote debugging by default. Please comment on [issue 3096](https://github.com/golang/vscode-go/issues/3096) if this impacts your workflows."
+					'ignorePortUsedInDlvDapWarning',
+					"`port` with 'dlv-dap' debugAdapter connects to [an external `dlv dap` server](https://github.com/golang/vscode-go/blob/master/docs/debugging.md#running-debugee-externally) to launch a program or attach to a process. Remove 'host' and 'port' from your launch.json if you have not launched a 'dlv dap' server."
 				);
 			}
 		}
-		if (debugConfiguration['debugAdapter'] === 'legacy') {
-			this.showWarning(
-				'ignoreLegacyDADeprecationWarning',
-				'Legacy debug adapter is deprecated. Please comment on [issue 3096](https://github.com/golang/vscode-go/issues/3096) if this impacts your workflows.'
-			);
-		}
-		if (
-			debugConfiguration['debugAdapter'] === 'dlv-dap' &&
-			debugConfiguration.request === 'launch' &&
-			debugConfiguration['port']
-		) {
-			this.showWarning(
-				'ignorePortUsedInDlvDapWarning',
-				"`port` with 'dlv-dap' debugAdapter connects to [a `dlv dap` server](https://github.com/golang/vscode-go/wiki/debugging#run-debugee-externally) to launch a program or attach to a process. Remove 'host'/'port' from your launch.json configuration if you have not launched a 'dlv dap' server."
-			);
-		}
 
 		const debugAdapter = debugConfiguration['debugAdapter'] === 'dlv-dap' ? 'dlv-dap' : 'dlv';
 

extension/src/goMain.ts

@@ -76,12 +76,24 @@ import { telemetryReporter } from './goTelemetry';
 
 const goCtx: GoExtensionContext = {};
 
-export async function activate(ctx: vscode.ExtensionContext): Promise<ExtensionAPI | undefined> {
+// Allow tests to access the extension context utilities.
+interface ExtensionTestAPI {
+	globalState: vscode.Memento;
+}
+
+export async function activate(ctx: vscode.ExtensionContext): Promise<ExtensionAPI | ExtensionTestAPI | undefined> {
 	if (process.env['VSCODE_GO_IN_TEST'] === '1') {
-		// Make sure this does not run when running in test.
-		return;
+		// TODO: VSCODE_GO_IN_TEST was introduced long before we learned about
+		// ctx.extensionMode, and used in multiple places.
+		// Investigate if use of VSCODE_GO_IN_TEST can be removed
+		// in favor of ctx.extensionMode and clean up.
+		if (ctx.extensionMode === vscode.ExtensionMode.Test) {
+			return { globalState: ctx.globalState };
+		}
+		// We shouldn't expose the memento in production mode even when VSCODE_GO_IN_TEST
+		// environment variable is set.
+		return; // Skip the remaining activation work.
 	}
-
 	const start = Date.now();
 	setGlobalState(ctx.globalState);
 	setWorkspaceState(ctx.workspaceState);

extension/src/goTelemetry.ts

@@ -21,6 +21,25 @@ export const GOPLS_MAYBE_PROMPT_FOR_TELEMETRY = 'gopls.maybe_prompt_for_telemetr
 // Exported for testing.
 export const TELEMETRY_START_TIME_KEY = 'telemetryStartTime';
 
+// Run our encode/decode function for the Date object, to be defensive
+// from vscode Memento API behavior change.
+// Exported for testing.
+export function recordTelemetryStartTime(storage: vscode.Memento, date: Date) {
+	storage.update(TELEMETRY_START_TIME_KEY, date.toJSON());
+}
+
+function readTelemetryStartTime(storage: vscode.Memento): Date | null {
+	const value = storage.get<string | number | Date>(TELEMETRY_START_TIME_KEY);
+	if (!value) {
+		return null;
+	}
+	const telemetryStartTime = new Date(value);
+	if (telemetryStartTime.toString() === 'Invalid Date') {
+		return null;
+	}
+	return telemetryStartTime;
+}
+
 enum ReporterState {
 	NOT_INITIALIZED,
 	IDLE,
@@ -153,9 +172,9 @@ export class TelemetryService {
 		this.active = true;
 		// record the first time we see the gopls with telemetry support.
 		// The timestamp will be used to avoid prompting too early.
-		const telemetryStartTime = globalState.get<Date>(TELEMETRY_START_TIME_KEY);
+		const telemetryStartTime = readTelemetryStartTime(globalState);
 		if (!telemetryStartTime) {
-			globalState.update(TELEMETRY_START_TIME_KEY, new Date());
+			recordTelemetryStartTime(globalState, new Date());
 		}
 	}
 
@@ -172,9 +191,11 @@ export class TelemetryService {
 		if (!isVSCodeTelemetryEnabled) return;
 
 		// Allow at least 7days for gopls to collect some data.
-		const now = new Date();
-		const telemetryStartTime = this.globalState.get<Date>(TELEMETRY_START_TIME_KEY, now);
-		if (daysBetween(telemetryStartTime, now) < 7) {
+		const telemetryStartTime = readTelemetryStartTime(this.globalState);
+		if (!telemetryStartTime) {
+			return;
+		}
+		if (daysBetween(telemetryStartTime, new Date()) < 7) {
 			return;
 		}
 

extension/src/language/legacy/goFormat.ts

@@ -12,7 +12,7 @@ import vscode = require('vscode');
 import { getGoConfig } from '../../config';
 import { toolExecutionEnvironment } from '../../goEnv';
 import { promptForMissingTool, promptForUpdatingTool } from '../../goInstallTools';
-import { getBinPath } from '../../util';
+import { getBinPath, resolvePath } from '../../util';
 import { killProcessTree } from '../../utils/processUtils';
 
 export class GoDocumentFormattingEditProvider implements vscode.DocumentFormattingEditProvider {
@@ -144,7 +144,7 @@ export function getFormatTool(goConfig: { [key: string]: any }): string {
 		return 'goimports';
 	}
 	if (formatTool === 'custom') {
-		return goConfig['alternateTools']['customFormatter'] || 'goimports';
+		return resolvePath(goConfig['alternateTools']['customFormatter'] || 'goimports');
 	}
 	return formatTool;
 }

extension/src/welcome.ts

@@ -12,7 +12,7 @@ import path = require('path');
 import semver = require('semver');
 import { extensionId } from './const';
 import { GoExtensionContext } from './context';
-import { extensionInfo } from './config';
+import { extensionInfo, getGoConfig } from './config';
 import { getFromGlobalState, updateGlobalState } from './stateUtils';
 import { createRegisterCommand } from './commands';
 
@@ -29,11 +29,7 @@ export class WelcomePanel {
 				}
 			});
 		}
-
-		// Show the Go welcome page on update.
-		if (!extensionInfo.isInCloudIDE && vscode.workspace.getConfiguration('go.showWelcome')) {
-			showGoWelcomePage();
-		}
+		showGoWelcomePage();
 	}
 
 	public static currentPanel: WelcomePanel | undefined;
@@ -278,6 +274,9 @@ function showGoWelcomePage() {
 }
 
 export function shouldShowGoWelcomePage(showVersions: string[], newVersion: string, oldVersion: string): boolean {
+	if (!extensionInfo.isInCloudIDE && getGoConfig().get('showWelcome') === false) {
+		return false;
+	}
 	if (newVersion === oldVersion) {
 		return false;
 	}

extension/test/gopls/extension.test.ts

@@ -10,7 +10,7 @@ import * as vscode from 'vscode';
 import { getGoConfig } from '../../src/config';
 import sinon = require('sinon');
 import { getGoVersion, GoVersion } from '../../src/util';
-import { GOPLS_MAYBE_PROMPT_FOR_TELEMETRY, TELEMETRY_START_TIME_KEY, TelemetryService } from '../../src/goTelemetry';
+import { GOPLS_MAYBE_PROMPT_FOR_TELEMETRY, recordTelemetryStartTime, TelemetryService } from '../../src/goTelemetry';
 import { MockMemento } from '../mocks/MockMemento';
 import { Env } from './goplsTestEnv.utils';
 
@@ -205,8 +205,7 @@ suite('Go Extension Tests With Gopls', function () {
 		const workspaceDir = path.resolve(testdataDir, 'gogetdocTestData');
 		await env.startGopls(path.join(workspaceDir, 'test.go'), undefined, workspaceDir);
 		const memento = new MockMemento();
-		memento.update(TELEMETRY_START_TIME_KEY, new Date('2000-01-01'));
-
+		recordTelemetryStartTime(memento, new Date('2000-01-01'));
 		const sut = new TelemetryService(env.languageClient, memento, [GOPLS_MAYBE_PROMPT_FOR_TELEMETRY]);
 		try {
 			await Promise.all([