vscode-codeql/CONTRIBUTING.md

Contributing

Hi there! We're thrilled that you'd like to contribute to this project. Your help is essential for keeping it great.

Contributions to this project are released to the public under the project's open source license.

Please note that this project is released with a Contributor Code of Conduct. By participating in this project you agree to abide by its terms.

Submitting a pull request

1. Fork and clone the repository
2. Set up a local build
3. Create a new branch: git checkout -b my-branch-name
4. Make your change
5. Push to your fork and submit a pull request
6. Pat yourself on the back and wait for your pull request to be reviewed and merged.

Here are a few things you can do that will increase the likelihood of your pull request being accepted:

• Follow the style guide.
• Write tests. Tests that don't require the VS Code API are located here. Integration tests that do require the VS Code API are located here.
• Keep your change as focused as possible. If there are multiple changes you would like to make that are not dependent upon each other, consider submitting them as separate pull requests.
• Write a good commit message.

Setting up a local build

Make sure you have a fairly recent version of vscode (>1.32) and are using nodejs version >=v10.13.0. (Tested on v10.15.1 and v10.16.0).

This repo uses Rush to handle package management, building, and other operations across multiple projects. See the Rush "Getting started as a developer" docs for more details.

If you plan on building from the command line, it's easiest if Rush is installed globally:

npm install -g @microsoft/rush

To get started, run:

rush update && rush build

Note that when you run the rush command from the globally installed version, it will examine the rushVersion property in the repo's rush.json, and if it differs from the globally installed version, it will download, cache, and run the version of Rush specified in the rushVersion property.

A few more things to know about using rush:

• Avoid running npm for any commands that install/link dependencies
• Instead use the rush equivalent: rush add <package>, rush update, etc.
• If you plan on only building via VS Code tasks, you don't need Rush installed at all, since those tasks run common/scripts/install-run-rush.js to bootstrap a locally installed and cached copy of Rush.

Building

Installing all packages (instead of npm install)

After updating any package.json file, or after checking or pulling a new branch, you need to make sure all the right npm packages are installed, which you would normally do via npm install in a single-project repo. With Rush, you need to do an "update" instead:

From VS Code

Terminal > Run Task... > Update

From the command line

rush update

Building all projects (instead of gulp)

Rush builds all projects in the repo, in dependency order, building multiple projects in parallel where possible. By default, the build also packages the extension itself into a .vsix file in the dist directory. To build:

From VS Code

Terminal > Run Build Task... (or just Ctrl+Shift+B with the default key bindings)

From the command line

rush build --verbose

Forcing a clean build

Rush does a reasonable job of detecting on its own which projects need to be rebuilt, but if you need to force a full rebuild of all projects:

From VS Code

Terminal > Run Task... > Rebuild

From the command line

rush rebuild --verbose

Note that rush rebuild performs a complete rebuild, whereas rush build performs an incremental build and in many cases will not need to do anything at all.

Installing

You can install the .vsix file from within VS Code itself, from the Extensions container in the sidebar:

More Actions... (top right) > Install from VSIX...

Or, from the command line, use something like (depending on where you have VSCode installed):

$ code --install-extension dist/vscode-codeql-*.vsix # normal VSCode installation
# or maybe
$ vscode/scripts/code-cli.sh --install-extension dist/vscode-codeql-*.vsix # if you're using the open-source version from a checkout of https://github.com/microsoft/vscode

Debugging

You can use VS Code to debug the extension without explicitly installing it. Just open this directory as a workspace in VS Code, and hit F5 to start a debugging session.

Running the unit/integration tests

Ensure the CODEQL_PATH environment variable is set to point to the codeql cli executable.

Outside of vscode, run:

npm run test && npm run integration

Alternatively, you can run the tests inside of vscode. There are several vscode launch configurations defined that run the unit and integration tests. They can all be found in the debug view.

Releasing (write access required)

1. Double-check the CHANGELOG.md contains all desired change comments and has the version to be released with date at the top.
2. Double-check that the extension package.json has the version you intend to release. If you are doing a patch release (as opposed to minor or major version) this should already be correct.
3. Trigger a release build on Actions by adding a new tag on branch main of the format vxx.xx.xx
4. Monitor the status of the release build in the Release workflow in the Actions tab.
5. Download the VSIX from the draft GitHub release at the top of the releases page that is created when the release build finishes.
6. Optionally unzip the .vsix and inspect its package.json to make sure the version is what you expect, or look at the source if there's any doubt the right code is being shipped.
7. Log into the Visual Studio Marketplace.
8. Click the ... menu in the CodeQL row and click Update.
9. Drag the .vsix file you downloaded from the GitHub release into the Marketplace and click Upload.
10. Go to the draft GitHub release, click 'Edit', add some summary description, and publish it.
11. Confirm the new release is marked as the latest release at https://github.com/github/vscode-codeql/releases.
12. If documentation changes need to be published, notify documentation team that release has been made.
13. Review and merge the version bump PR that is automatically created by Actions.

Resources

• How to Contribute to Open Source
• Using Pull Requests
• GitHub Help