12 KiB
Contributing
We welcome your contributions and thank you for working to improve the Go development experience in VS Code.
This guide will explain the process of setting up your development environment to work on the VS Code Go extension, as well as the process of sending out your change for review. If you're interested in testing the master branch or pre-releases of the extension, please see the Go Nightly documentation.
Our canonical Git repository is located at https://go.googlesource.com/vscode-go and https://github.com/golang/vscode-go is a mirror.
Before you start coding
If you are interested in fixing a bug or contributing a feature, please file an issue first. Wait for a project maintainer to respond before you spend time coding.
If you wish to work on an existing issue, please add a comment saying so, as someone may already be working on it. A project maintainer may respond with advice on how to get started. If you're not sure which issues are available, search for issues with the help wanted label.
Ask for help
The VS Code Go maintainers are reachable via the issue tracker and the #vscode-dev channel in the Gophers Slack. Please reach out on Slack with questions, suggestions, or ideas. If you have trouble getting started on an issue, we'd be happy to give pointers and advice.
Language Server (gopls
)
Many of the language features like auto-completion, documentation, diagnostics are implemented
by the Go language server (gopls
).
This extension communicates with gopls
using vscode LSP client library from language/goLanguageServer.ts
.
For extending the language features or fixing bugs, please follow gopls
's
contribution guide.
Debug Adapter (dlv dap
)
Debugging features are implemented by Delve (dlv
) and its native DAP implementation
(dlv dap
).
- goDebugConfiguration.ts: where launch configuration massaging occurs.
- goDebugFactory.ts: where a thin adapter that communicates with the
dlv dap
process is defined. - github.com/go-delve/delve: where native DAP implementation in Delve exists.
For extending the features of Delve, please follow Delve
project's contribution guide.
The debugging feature documentation has a dedicated section for tips for development (See "Developing" section).
Developing
Setup
-
Install node. Note: make sure that you are using
npm v7
or higher. The file format forpackage-lock.json
(changed significantly)[https://docs.npmjs.com/cli/v7/configuring-npm/package-lock-json#file-format] innpm v7
. -
Clone the repository, run
npm ci
, and open VS Code:git clone https://go.googlesource.com/vscode-go cd vscode-go/extension npm ci code .
Lint
You can run npm run lint
on the command-line to check for lint errors in your program. You can also use the TSLint plugin to see errors as you code.
Run
To run the extension with your patch, open the Run view (Ctrl+Shift+D
or ⌘+⇧+D
), select Launch Extension
, and click the Play button (F5
).
This will open a new VS Code window with the title [Extension Development Host]
. You can then open a folder that contains Go code and try out your changes.
You can also set breakpoints to debug your change.
If you make subsequent edits in the codebase, you can reload (Ctrl+R
or ⌘+R
) the [Extension Development Host]
instance of VS Code, which will load the new code. The debugger will automatically reattach.
Test
export GOPATH=/path/to/gopath/for/test
cd extension
-- most extension development work is done in theextension
directory.go run tools/installtools/main.go
-- this will install all tools in theGOPATH/bin
built from master/main.- There are currently two different types of tests in this repo:
npm run unit-test
: this runs unit tests defined intest/unit
. They are light-weight tests that don't requirevscode
APIs.npm run test
: this runs the integration tests defined intest/integration
andtest/gopls
. They test logic that involvevscode
APIs - which requires actually downloading & running Visual Studio Code (code
) and loading the compiled extension/test code in it.
- Before sending a CL, make sure to run
npm run lint
: this runs linter.go run tools/generate.go -w=false -gopls=true
: this checks generated documentations are up-to-date.
Testing Tips
(1) Running only a subset of integration or unit tests:
When running them from terminal:
- Option 1: Utilize
MOCHA_GREP
environment variable. That is equivalent withmocha --grep
flag that runs tests matching the given string or regexp. E.g.MOCHA_GREP=gopls npm run test
which runs all integration tests whose suite/test names contain"gopls"
. - Option 2: modify the test source code and set the
only
orskip
depending on your need. If necessary, you can also modifytest/integration/index.ts
ortest/gopls/index.ts
to include only the test files you want to focus on. Make sure to revert them before sending the changes for review.
(2) Debugging tests from VS Code:
.vscode/launch.json
defines test launch configurations. To run the tests locally, open the Run view (Ctrl+Shift+D
), select the relevant launch configuration, and hit the Play button (F5
). Output and results of the tests, including any logging written with console.log
will appear in the DEBUG CONSOLE
tab.
You can supply environment variables (e.g. MOCHA_GREP
) by modifying the launch configuration entry's env
property.
Launch Unit Tests
: runs unit tests intest/unit
(same asnpm run unit-test
)Launch Extension Tests
: runs tests intest/integration
directory (similar tonpm run test
but runs only tests undertest/integration
directory)Launch Extension Tests with Gopls
: runs tests intest/gopls directory (similar to
npm run testbut runs only tests under
test/gopls` directory)
When you want to filter tests while debugging, utilize the MOCAH_GREP
environment variable discussed previously - i.e., set the environment variable in the env
property of the launch configuration.
(3) Using different versions of tools.
The tests will pick tools found from GOPATH/bin
first. So, install the versions you want there.
Running/Debugging the Extension
Select the Launch Extension
configuration, and hit the Play button (F5
). This will build the extension and start a new VS Code window with the title "[Extension Development Host]"
that uses the newly built extension. This instance has the node.js debugger attached automatically. You can debug using the VS Code Debug UI of the main window (e.g. set breakpoints, inspect variables, step, etc)
The VS Code window may have the folder or file used during your previous testing. If you want to change the folder during testing, close the folder by using "File > Close Folder", and open a new folder from the VS Code window under test.
Debugging interaction with gopls
When developing features in gopls
, you may need to attach a debugger to gopls
and configure the extension to connect to the gopls
instance using the gopls deamon mode.
- Start a gopls in deamon mode:
gopls -listen=:37374 -logfile=auto -debug=:0 serve
Or, if you use vscode for gopls development, you can configure launch.json
of the x/tools/gopls
project:
...
{
"name": "Launch Gopls",
"type": "go",
"request": "launch",
"mode": "auto",
"program": "${workspaceFolder}/gopls",
"args": ["-listen=:37374", "-logfile=auto", "-debug=:0"],
"cwd": "<... directory where you want to run your gopls from ...",
}
...
-
Start the extension debug session using the
Launch Extension
configuration. -
Configure the settings.json of the project open in the
"[Extension Development Host]"
window to startgopls
that connects to the gopls we started in the step 1.
"go.languageServerFlags": ["-remote=:37374", "-rpc.trace"]
Sideload
After making changes to the extension, you may want to test it end-to-end instead of running it in debug mode. To do this, you can sideload the extension.
-
cd
into theextension
directory. -
Install all dependencies by running
npm ci
. -
Run
npx vsce package
. This will generate a file with a.vsix
extension in your current directory.npm install -g vsce cd vscode-go npm ci vsce package
-
Open a VS Code window, navigate to the Extensions view, and disable or uninstall the default Go extension.
-
Click on the "..." in the top-right corner, select "Install from VSIX...", and choose the generated VSIX file. Alternatively, you can run
code --install-extension path/to/go.vsix
or open the Command Palette and run theExtensions: Install from VSIX...
command.
Mail your change for review
Once you have coded, built, and tested your change, it's ready for review! There are two ways to mail your change: (1) through a GitHub pull request (PR), or (2) through a Gerrit code review.
In either case, code review will happen in Gerrit, which is used for all repositories in the Go project. We strongly recommend the Gerrit code review if you plan to send many changes. GitHub pull requests will be mirrored into Gerrit, so you can follow a more traditional GitHub workflow, but you will still have to look at Gerrit to read comments.
The easiest way to start is by reading this detailed guide for contributing to the Go project. Important things to note are:
- You will need to sign the Google CLA.
- Your commit message should follow the standards described on the Commit Message Wiki.
- Your change should include tests (if possible).
Once you've sent out your change, a maintainer will take a look at your contribution within a few weeks. If you don't hear back, feel free to ping the issue or send a message to the #vscode-dev channel of the Gophers Slack.
Presubmit Test in CI
When you mail your CL or upload a new patch to an existing CL, AND
you or a fellow contributor assigns the Run-TryBot=+1
label in Gerrit, the test command defined in
build/all.bash
will run by Kokoro
, which is Jenkins-like Google infrastructure
for running Dockerized tests. Kokoro
will post the result as a comment, and add its TryBot-Result
vote after each test run completes.
To force a re-run of the Kokoro CI, add comment kokoro rerun
to the CL.