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 installed recent versions of vscode, node, and npm. Check the engines block in package.json file for compatible versions. Earlier versions may work, but we no longer test against them.

To automatically switch to the correct version of node, we recommend using nvm, which will pick-up the node version from .nvmrc.

Installing all packages

From the command line, go to the directory extensions/ql-vscode and run

npm install

Building the extension

From the command line, go to the directory extensions/ql-vscode and run

npm run build
npm run watch

Alternatively, you can build the extension within VS Code via Terminal > Run Build Task... (or Ctrl+Shift+B with the default key bindings). And you can run the watch command via Terminal > Run Task and then select npm watch from the menu.

Before running any of the launch commands, be sure to have run the build command to ensure that the JavaScript is compiled and the resources are copied to the proper location.

We recommend that you keep npm run watch running in the backgound and you only need to re-run npm run build in the following situations:

1. on first checkout
2. whenever any of the non-TypeScript resources have changed

Installing the extension

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.

Storybook

You can use Storybook to preview React components outside VSCode. Inside the extensions/ql-vscode directory, run:

npm run storybook

Your browser should automatically open to the Storybook UI. Stories live in the src/stories directory.

Alternatively, you can start Storybook inside of VSCode. There is a VSCode launch configuration for starting Storybook. It can be found in the debug view.

More information about Storybook can be found inside the Overview page once you have launched Storybook.

Testing

We have several types of tests:

• Unit tests: these live in the tests/pure-tests/ directory
• View tests: these live in src/view/variant-analysis/__tests__/
• VSCode integration tests: these live in src/vscode-tests/no-workspace and src/vscode-tests/minimal-workspace
• CLI integration tests: these live in src/vscode-tests/cli-integration

The CLI integration tests require an instance of the CodeQL CLI to run so they will require some extra setup steps. When adding new tests to our test suite, please be mindful of whether they need to be in the cli-integration folder. If the tests don't depend on the CLI, they are better suited to being a VSCode integration test.

Running the tests

1. From the terminal

First move into the extensions/ql-vscode directory. Then, depending on which tests you want to run, use the appropriate command to run the tests:

• Unit tests: npm run test:unit
• View Tests: npm test:view
• VSCode integration tests: npm run integration

CLI integration tests

The CLI integration tests require the CodeQL standard libraries in order to run so you will need to clone a local copy of the github/codeql repository.

1. Set the TEST_CODEQL_PATH environment variable: running from a terminal, you must set the TEST_CODEQL_PATH variable to point to a checkout of the github/codeql repository. The appropriate CLI version will be downloaded as part of the test.

2. Run your test command:

cd extensions/ql-vscode && npm run cli-integration

2. From VSCode

Alternatively, you can run the tests inside of VSCode. There are several VSCode launch configurations defined that run the unit and integration tests.

You will need to run tests using a task from inside of VS Code, under the "Run and Debug" view:

• Unit tests: run the Launch Unit Tests - React task
• View Tests: run the Launch Unit Tests task
• VSCode integration tests: run the Launch Unit Tests - No Workspace and Launch Unit Tests - Minimal Workspace tasks

CLI integration tests

The CLI integration tests require the CodeQL standard libraries in order to run so you will need to clone a local copy of the github/codeql repository.

1. Set the TEST_CODEQL_PATH environment variable: running from a terminal, you must set the TEST_CODEQL_PATH variable to point to a checkout of the github/codeql repository. The appropriate CLI version will be downloaded as part of the test.

2. Set the codeql path in VSCode's launch configuration: open launch.json and under the Launch Integration Tests - With CLI section, uncomment the "${workspaceRoot}/../codeql" line. If you've cloned the github/codeql repo to a different path, replace the value with the correct path.

3. Run the VSCode task from the "Run and Debug" view called Launch Integration Tests - With CLI.

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.

   • Go through all recent PRs and make sure they are properly accounted for.
   • Make sure all changelog entries have links back to their PR(s) if appropriate.

2. Double-check that the node version we're using matches the one used for VS Code. If it doesn't, you will then need to update the node version in the following files:

   • .nvmrc - this will enable nvm to automatically switch to the correct node version when you're in the project folder
   • .github/workflows/main.yml - all the "node-version: " settings
   • .github/workflows/release.yml - the "node-version: " setting

3. Double-check that the extension package.json and package-lock.json have 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.

4. Create a PR for this release:

   • This PR will contain any missing bits from steps 1 and 2. Most of the time, this will just be updating CHANGELOG.md with today's date.
   • Create a new branch for the release named after the new version. For example: v1.3.6
   • Create a new commit with a message the same as the branch name.
   • Create a PR for this branch.
   • Wait for the PR to be merged into main

5. Switch to main and add a new tag on the main branch with your new version (named after the release), e.g.

   git checkout main
   git tag v1.3.6
   

   If you've accidentally created a badly named tag, you can delete it via

   git tag -d badly-named-tag
   

6. Push the new tag up:

   a. If you're using a fork of the repo:

   git push upstream refs/tags/v1.3.6
   

   b. If you're working straight in this repo:

   git push origin refs/tags/v1.3.6
   

   This will trigger a release build on Actions.

   • IMPORTANT Make sure you are on the main branch and your local checkout is fully updated when you add the tag.
   • If you accidentally add the tag to the wrong ref, you can just force push it to the right one later.

7. Monitor the status of the release build in the Release workflow in the Actions tab.

   • DO NOT approve the "publish" stages of the workflow yet.

8. Download the VSIX from the draft GitHub release at the top of the releases page that is created when the release build finishes.

9. 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.

10. Install the .vsix file into your vscode IDE and ensure the extension can load properly. Run a single command (like run query, or add database).

11. Go to the actions tab of the vscode-codeql repository and select the Release workflow.

    • If there is an authentication failure when publishing, be sure to check that the authentication keys haven't expired. See below.

12. Approve the deployments of the correct Release workflow. This will automatically publish to Open VSX and VS Code Marketplace.

13. Go to the draft GitHub release in the releases tab of the repository, click 'Edit', add some summary description, and publish it.

14. Confirm the new release is marked as the latest release at https://github.com/github/vscode-codeql/releases.

15. If documentation changes need to be published, notify documentation team that release has been made.

16. Review and merge the version bump PR that is automatically created by Actions.

Secrets and authentication for publishing

Repository administrators, will need to manage the authentication keys for publishing to the VS Code marketplace and Open VSX. Each requires an authentication token. The VS Code marketplace token expires yearly.

To regenerate the Open VSX token:

1. Log in to the user settings page on Open VSX.
2. Make sure you are a member of the GitHub namespace.
3. Go to the Access Tokens page and generate a new token.
4. Update the secret in the publish-open-vsx environment in the project settings.

To regenerate the VSCode Marketplace token, please see our internal documentation. Note that Azure DevOps PATs expire every 90 days and must be regenerated.

Resources

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