Thanks so much for wanting to contribute to the Python Extension! This page is meant to be a practical, end-to-end guide. If you follow it, you should end up with a PR that is easy to review and passes CI!

• If you are fixing a bug or making a user-facing change: start from an issue.
  • Find an existing issue (recommended), or create a new one.
• If you’re looking for a good first issue, check for issues labeled help wanted.
• If your change is very small and obvious (typo, trivial refactor needed for a fix), you can often open a PR directly.

Before we can accept a pull request from you, you'll need to sign a Contributor License Agreement (CLA). This is a one-time requirement for Microsoft projects in GitHub. You can read more about Contribution License Agreements on Wikipedia.

However, you don't have to do this up-front. You can simply clone, fork, and submit your pull-request as usual.

When your pull-request is created, it is checked by a CLA bot, which will tell you how to sign a CLA if necessary. Once you have signed it, all future pull-requests will not require you to sign a new CLA.

This repo contains:

• TypeScript code for the VS Code Python extension (most changes).
• Python helper scripts under python_files/.

If you’re unsure where a change belongs, open an issue and ask!

For all setup details and coding guidelines, start here! It will walk you through install dependencies and building the extension

• https://github.com/microsoft/vscode-python/wiki/Coding

In VS Code, use the debug configuration that launches the extension (often named “Extension”).

Sanity check:

Validate something observable:

• the extension activates
• settings load
• the feature you changed is reachable

Create a topic branch from main:

git fetch upstream
git checkout -b <your-branch-name> upstream/main

Use a descriptive name, e.g. fix-pytest-discovery, docs-testing-guide.

• Keep PRs focused: one logical change per PR.
• Avoid drive-by formatting.
• Prefer small, well-named commits.
• Add comments where they clarify intent or non-obvious behavior.
• If you use AI assistance, review the diff carefully and validate behavior locally.

Most PRs should include automated tests.

• If you changed TypeScript behavior, add or update a test file (common patterns include *.unit.test.ts, *.test.ts, *.smoke.test.ts).
• If you changed Python scripts under python_files/, add/update tests under python_files/tests/.

If tests are not feasible, explain why in your PR so maintainers can advise on the right coverage (or alternatives).

For details on test levels and how to run them, see: https://github.com/microsoft/vscode-python/wiki/Testing

Run the smallest thing that gives you confidence.

npm run test:unittests

If you only changed a small area, you can often filter to a single suite via the guidance in the Testing wiki.

npm run check-python

If you’re unsure which suite to run, start with unit tests and expand from there.

Make sure your commit messages are meaningful and your branch is up to date.

git status
# review changes

git add -A
git commit -m "<short summary>"

1. Push your branch to your fork:

git push -u origin <your-branch-name>

2. Open a PR against microsoft/vscode-python:main.

Include:

• A link to the issue (e.g. “Fixes #12345” or “Related to #12345”).
• What changed and why (1–3 short sentences).
• How you tested:
  • list the commands you ran (and/or)
  • describe manual verification steps
• Anything reviewers should pay attention to (risk, edge cases, follow-ups).
• If you have permission to apply labels, add the appropriate ones (e.g. debt, bug, feature-request). Otherwise, mention the suggested labels in the PR description.

• CI will run and report status checks.
• Maintainers may request changes.
• If you need to update the PR, push more commits to the same branch.

• If you’re blocked, open a draft PR early and ask questions in the description.
• For discussion-style questions, consider GitHub Discussions: https://github.com/microsoft/vscode-python/discussions