8000 Coding · microsoft/vscode-python Wiki · GitHub
[go: up one dir, main page]
Skip to content

Coding

Jump to bottom
Karthik Nadig edited this page Mar 28, 2025 · 25 revisions

Prerequisites

  1. Node.js 20.18.1
  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:
  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
# Windows:
# cmd: ".venv/Scripts/activate.bat"
# PS: & ".venv/Scripts/Activate.ps1"
# gitbash/bash: source .venv/Scripts/activate

# Linux/Mac:
# bash/zsh: source .venv/bin/activate
# PS: & ".venv/bin/Activate.ps1"

Linux/Mac (sh/bash):

source .venv/bin/activate
.venv/bin/python -m pip install nox
nox --session setup_repo

Linux/Mac (PS):

& ".venv/bin/Activate.ps1"
.venv/bin/python -m pip install nox
nox --session setup_repo

Windows (PS):

& ".venv/Scripts/Activate.ps1"
.venv/Scripts/python -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.

Using a Proposed API

Follow these steps to incorporate a proposed API into your extension:

  1. Enable the Proposed API in Your Extension: Refer to the official guide for enabling proposed APIs in a VS Code extension: Using Proposed API.

  2. Add Your Extension's Dependency to the Proposed API: Update the vscode-distro repository to include your extension's dependency on the proposed API. Use this example PR as a reference: Example PR in vscode-distro.

  3. Wait for the vscode-distro PR to Be Merged: Once the vscode-distro PR is merged, note the new hash generated from the merged changes.

  4. Update VS Code to Pull the Latest Distro Changes: Update the distro field in the package.json file in the vscode repository to use the new hash. Use this example PR as a reference: Example PR in vscode.

Usage

Development

Reference

Clone this wiki locally
0