Coding

Prerequisites

1. Node.js 18.17.0
2. Rust 2021
3. An upstream-supported version of Python
4. Windows, macOS, or Linux
5. Visual Studio Code
6. The following VS Code extensions:
   • ESlint
   • Prettier
   • Black extension
7. Have an issue which has a "needs PR" label (feel free to indicate you would like to provide a PR for the issue so others don't work on it as well)

Guidelines

General

Python or TypeScript?

Always prefer to write Python code over TypeScript code. Not only does that give us more opportunity to use the extension ourself but it makes it easier for our users to contribute back.

Comments

• Add comments to explain non-obvious decisions, or contextual knowledge that can be forgotten.
• Conciseness is important.
• Comment should start with an uppercase letter, and end with a period (i.e. be complete sentences).
• If a question can be answered by looking at the code, a comment is probably unnecessary.
• A comment should answer "Why was this done this way?" two years down the line. If it doesn't, it is probably unnecessary, or should be rewritten.
• If some logic depends on external factors or tools, a comment capturing the assumptions made at implementation time may be useful.
• If the comment refers to work that needs to be done, create an issue for it and link it in your comment.

Python

Formatting

Follow PEP 8 and use Ruff extension.

3rd-party Packages

• Always use pip-compile --generate-hashes.
• Make sure all requirements files are named requirements.txt.

TypeScript

Formatting

Use Prettier.

Typing

• Do lean into TypeScript's types; typing is good. 😄
• Do not silence ESLint warnings unnecessarily; have justifications as to why.
• Do not rely on the ! operator, if possible; assume the typing is correct.
• Do use undefined when necessary; do not use null.

Third-party Packaging

• Make sure in package.json that the vscode "engine" matches what @types/vscode is set to (and vice-versa).

Building

Do note that building the extension is to discover compiler issues, not to specifically launch the extension in a Development Extension Host window (press F5).

git clone https://github.com/microsoft/vscode-python
cd vscode-python
npm ci
python3 -m venv .venv
# Activate the virtual environment as appropriate for your shell, For example, If you're on cmd, you can use...
# ".venv/Scripts/activate.bat"
# On bash/zsh it's ...
source .venv/bin/activate
# The Python code in the extension is formatted using Black.
python3 -m pip install nox
nox --session setup_repo

• If you run into permission problem when running command "nox --session setup_repo" on MacOS, use sudo.

To build without translations, set the DISABLE_TRANSLATIONS environment variable to true.

If you see warnings that The engine "vscode" appears to be invalid., you can ignore these. If python3 is not available for some reason, you can use python instead.

Incremental Build

Run the Compile build task from the Run Build Task... command picker (short cut CTRL+SHIFT+B or ⇧⌘B). This will leave build task running in the background and which will re-run as files are edited and saved. You can see the output from either task in the Terminal panel (use the selector to choose which output to look at).

You can also compile from the command-line. For a full compile you can use:

npx gulp prePublishNonBundle

For incremental builds you can use the following commands depending on your needs:

npm run compile

Sometimes you will need to run npm run clean and even rm -r out. This is especially true if you have added or removed files.

Web version of extension

To build the web version of the extension, run the following command.

npx gulp webpack

Sometimes you will need to run npm run clean and even rm -r out. This is especially true if you have added or removed files.