package.json: add deprecation note for legacy tools settings

By adding the deprecation notes, the current users of these settings will notice the deprecation when they happen to edit their settings.json. Moreover, VS Code will exclude them from the default settings UI and autocompletion list, which will help users not getting distracted by these old settings. Updates #2799 Change-Id: I771dd5aeb6f826882d2c234e80862a8fb7d45670 Reviewed-on: https://go-review.googlesource.com/c/vscode-go/+/501206 Reviewed-by: Jamal Carvalho <[email protected]> Run-TryBot: Hyang-Ah Hana Kim <[email protected]> TryBot-Result: kokoro <[email protected]>
golang · Jun 6, 2023 · 0b6803b · 0b6803b
1 parent df36d6f
commit 0b6803b
Show file tree

Hide file tree

Showing 2 changed files with 52 additions and 28 deletions.
diff --git a/docs/settings.md b/docs/settings.md
@@ -55,17 +55,19 @@ Alternate tools or alternate paths for the same tools used by the Go extension.
 | `dlv` | Alternate tool to use instead of the dlv binary or alternate path to use for the dlv binary. <br/> Default: `"dlv"` |
 | `go` | Alternate tool to use instead of the go binary or alternate path to use for the go binary. <br/> Default: `"go"` |
 | `gopls` | Alternate tool to use instead of the gopls binary or alternate path to use for the gopls binary. <br/> Default: `"gopls"` |
-### `go.autocompleteUnimportedPackages`
+### `go.autocompleteUnimportedPackages (deprecated)`
 
+Code completion without the language server is deprecated. Enable the Go language server (`#go.useLanguageServer#`).
 Include unimported packages in auto-complete suggestions. Not applicable when using the language server.
 
 Default: `false`
 ### `go.buildFlags`
 
 Flags to `go build`/`go test` used during build-on-save or running tests. (e.g. ["-ldflags='-s'"]) This is propagated to the language server if `gopls.build.buildFlags` is not specified.
-### `go.buildOnSave`
+### `go.buildOnSave (deprecated)`
 
-Compiles code on file save using 'go build' or 'go test -c'. Options are 'workspace', 'package', or 'off'.  Not applicable when using the language server's diagnostics. See 'go.languageServerExperimentalFeatures.diagnostics' setting.<br/>
+Enable the Go language server (`#go.useLanguageServer#`) to diagnose compile errors.
+Compiles code on file save using 'go build' or 'go test -c'. Not applicable when using the language server.<br/>
 Allowed Options: `package`, `workspace`, `off`
 
 Default: `"package"`
@@ -168,8 +170,9 @@ Default: `"Off"`
 If true, tests will not run concurrently. When a new test run is started, the previous will be cancelled.
 
 Default: `false`
-### `go.docsTool`
+### `go.docsTool (deprecated)`
 
+Documentation support without the language server is deprecated. Enable the Go language server (`#go.useLanguageServer#`).
 Pick 'godoc' or 'gogetdoc' to get documentation. Not applicable when using the language server.<br/>
 Allowed Options: `godoc`, `gogetdoc`, `guru`
 
@@ -248,19 +251,22 @@ Default: `"default"`
 ### `go.generateTestsFlags`
 
 Additional command line flags to pass to `gotests` for generating tests.
-### `go.gocodeAutoBuild`
+### `go.gocodeAutoBuild (deprecated)`
 
+`gocode` is deprecated by the Go language server. Enable the Go language server (`#go.useLanguageServer#`).
 Enable gocode's autobuild feature. Not applicable when using the language server.
 
 Default: `false`
-### `go.gocodeFlags`
+### `go.gocodeFlags (deprecated)`
 
+`gocode` is deprecated by the Go language server. Enable the Go language server (`#go.useLanguageServer#`).
 Additional flags to pass to gocode. Not applicable when using the language server.
 
 Default: `["-builtin", "-ignore-case", "-unimported-packages"]`
-### `go.gocodePackageLookupMode`
+### `go.gocodePackageLookupMode (deprecated)`
 
-Used to determine the Go package lookup rules for completions by gocode. Only applies when using nsf/gocode. Latest versions of the Go extension uses mdempsky/gocode by default. Not applicable when using the language server.<br/>
+`gocode` is deprecated by the Go language server. Enable the Go language server (`#go.useLanguageServer#`).
+Used to determine the Go package lookup rules for completions by gocode. Not applicable when using the language server.<br/>
 Allowed Options: `go`, `gb`, `bzl`
 
 Default: `"go"`
@@ -270,16 +276,19 @@ Specify GOPATH here to override the one that is set as environment variable. The
 ### `go.goroot`
 
 Specifies the GOROOT to use when no environment variable is set.
-### `go.gotoSymbol.ignoreFolders`
+### `go.gotoSymbol.ignoreFolders (deprecated)`
 
+Code navigation without the language server is deprecated. Enable the Go language server (`#go.useLanguageServer#`).
 Folder names (not paths) to ignore while using Go to Symbol in Workspace feature. Not applicable when using the language server.
-### `go.gotoSymbol.includeGoroot`
+### `go.gotoSymbol.includeGoroot (deprecated)`
 
+Code navigation without the language server is deprecated. Enable the Go language server (`#go.useLanguageServer#`).
 If false, the standard library located at $GOROOT will be excluded while using the Go to Symbol in File feature. Not applicable when using the language server.
 
 Default: `false`
-### `go.gotoSymbol.includeImports`
+### `go.gotoSymbol.includeImports (deprecated)`
 
+Code navigation without the language server is deprecated. Enable the Go language server (`#go.useLanguageServer#`).
 If false, the import statements will be excluded while using the Go to Symbol in File feature. Not applicable when using the language server.
 
 Default: `false`
@@ -397,8 +406,9 @@ Specifies Lint tool name.<br/>
 Allowed Options: `staticcheck`, `golint`, `golangci-lint`, `revive`
 
 Default: `"staticcheck"`
-### `go.liveErrors`
+### `go.liveErrors (deprecated)`
 
+Real-time diagnostics without the language server is deprecated. Enable the Go language server (`#go.useLanguageServer#`).
 Use gotype on the file currently being edited and report any semantic or syntactic errors found after configured delay. Not applicable when using the language server.
 | Properties | Description |
 | --- | --- |
@@ -553,13 +563,15 @@ Trace the communication between VS Code and the Go language server.<br/>
 Allowed Options: `off`, `messages`, `verbose`
 
 Default: `"off"`
-### `go.useCodeSnippetsOnFunctionSuggest`
+### `go.useCodeSnippetsOnFunctionSuggest (deprecated)`
 
+Code completion without the language server is deprecated. Enable the Go language server (`#go.useLanguageServer#`) and use [`gopls's `ui.completion.usePlaceholders` setting](https://github.com/golang/vscode-go/wiki/settings#uicompletionuseplaceholders) instead.
 Complete functions with their parameter signature, including the variable type. Not propagated to the language server.
 
 Default: `false`
-### `go.useCodeSnippetsOnFunctionSuggestWithoutType`
+### `go.useCodeSnippetsOnFunctionSuggestWithoutType (deprecated)`
 
+Code completion without the language server is deprecated. Enable the Go language server (`#go.useLanguageServer#`) and use [`gopls's `ui.completion.usePlaceholders` setting](https://github.com/golang/vscode-go/wiki/settings#uicompletionuseplaceholders) instead.
 Complete functions with their parameter signature, excluding the variable types. Use `gopls.usePlaceholders` when using the language server.
 
 Default: `false`

diff --git a/package.json b/package.json
@@ -1121,8 +1121,9 @@
             "off"
           ],
           "default": "package",
-          "description": "Compiles code on file save using 'go build' or 'go test -c'. Options are 'workspace', 'package', or 'off'.  Not applicable when using the language server's diagnostics. See 'go.languageServerExperimentalFeatures.diagnostics' setting.",
-          "scope": "resource"
+          "description": "Compiles code on file save using 'go build' or 'go test -c'. Not applicable when using the language server.",
+          "scope": "resource",
+          "markdownDeprecationMessage": "Enable the Go language server (`#go.useLanguageServer#`) to diagnose compile errors."
         },
         "go.buildFlags": {
           "type": "array",
@@ -1516,13 +1517,15 @@
             "-unimported-packages"
           ],
           "description": "Additional flags to pass to gocode. Not applicable when using the language server.",
-          "scope": "resource"
+          "scope": "resource",
+          "markdownDeprecationMessage": "`gocode` is deprecated by the Go language server. Enable the Go language server (`#go.useLanguageServer#`)."
         },
         "go.gocodeAutoBuild": {
           "type": "boolean",
           "default": false,
           "description": "Enable gocode's autobuild feature. Not applicable when using the language server.",
-          "scope": "resource"
+          "scope": "resource",
+          "markdownDeprecationMessage": "`gocode` is deprecated by the Go language server. Enable the Go language server (`#go.useLanguageServer#`)."
         },
         "go.gocodePackageLookupMode": {
           "type": "string",
@@ -1532,26 +1535,30 @@
             "bzl"
           ],
           "default": "go",
-          "description": "Used to determine the Go package lookup rules for completions by gocode. Only applies when using nsf/gocode. Latest versions of the Go extension uses mdempsky/gocode by default. Not applicable when using the language server.",
-          "scope": "resource"
+          "description": "Used to determine the Go package lookup rules for completions by gocode. Not applicable when using the language server.",
+          "scope": "resource",
+          "markdownDeprecationMessage": "`gocode` is deprecated by the Go language server. Enable the Go language server (`#go.useLanguageServer#`)."
         },
         "go.useCodeSnippetsOnFunctionSuggest": {
           "type": "boolean",
           "default": false,
           "description": "Complete functions with their parameter signature, including the variable type. Not propagated to the language server.",
-          "scope": "resource"
+          "scope": "resource",
+          "markdownDeprecationMessage": "Code completion without the language server is deprecated. Enable the Go language server (`#go.useLanguageServer#`) and use [`gopls's `ui.completion.usePlaceholders` setting](https://github.com/golang/vscode-go/wiki/settings#uicompletionuseplaceholders) instead."
         },
         "go.useCodeSnippetsOnFunctionSuggestWithoutType": {
           "type": "boolean",
           "default": false,
           "description": "Complete functions with their parameter signature, excluding the variable types. Use `gopls.usePlaceholders` when using the language server.",
-          "scope": "resource"
+          "scope": "resource",
+          "markdownDeprecationMessage": "Code completion without the language server is deprecated. Enable the Go language server (`#go.useLanguageServer#`) and use [`gopls's `ui.completion.usePlaceholders` setting](https://github.com/golang/vscode-go/wiki/settings#uicompletionuseplaceholders) instead."
         },
         "go.autocompleteUnimportedPackages": {
           "type": "boolean",
           "default": false,
           "description": "Include unimported packages in auto-complete suggestions. Not applicable when using the language server.",
-          "scope": "resource"
+          "scope": "resource",
+          "markdownDeprecationMessage": "Code completion without the language server is deprecated. Enable the Go language server (`#go.useLanguageServer#`)."
         },
         "go.docsTool": {
           "type": "string",
@@ -1562,7 +1569,8 @@
             "godoc",
             "gogetdoc",
             "guru"
-          ]
+          ],
+          "markdownDeprecationMessage": "Documentation support without the language server is deprecated. Enable the Go language server (`#go.useLanguageServer#`)."
         },
         "go.useLanguageServer": {
           "type": "boolean",
@@ -1648,13 +1656,15 @@
           "type": "boolean",
           "default": false,
           "description": "If false, the import statements will be excluded while using the Go to Symbol in File feature. Not applicable when using the language server.",
-          "scope": "resource"
+          "scope": "resource",
+          "markdownDeprecationMessage": "Code navigation without the language server is deprecated. Enable the Go language server (`#go.useLanguageServer#`)."
         },
         "go.gotoSymbol.includeGoroot": {
           "type": "boolean",
           "default": false,
           "description": "If false, the standard library located at $GOROOT will be excluded while using the Go to Symbol in File feature. Not applicable when using the language server.",
-          "scope": "resource"
+          "scope": "resource",
+          "markdownDeprecationMessage": "Code navigation without the language server is deprecated. Enable the Go language server (`#go.useLanguageServer#`)."
         },
         "go.enableCodeLens": {
           "type": "object",
@@ -1739,7 +1749,8 @@
             "delay": 500
           },
           "description": "Use gotype on the file currently being edited and report any semantic or syntactic errors found after configured delay. Not applicable when using the language server.",
-          "scope": "resource"
+          "scope": "resource",
+          "markdownDeprecationMessage": "Real-time diagnostics without the language server is deprecated. Enable the Go language server (`#go.useLanguageServer#`)."
         },
         "go.removeTags": {
           "type": "object",
@@ -1908,7 +1919,8 @@
           },
           "default": [],
           "description": "Folder names (not paths) to ignore while using Go to Symbol in Workspace feature. Not applicable when using the language server.",
-          "scope": "resource"
+          "scope": "resource",
+          "markdownDeprecationMessage": "Code navigation without the language server is deprecated. Enable the Go language server (`#go.useLanguageServer#`)."
         },
         "go.delveConfig": {
           "type": "object",