| macOS/Windows CI | Linux CI | Rolling CI (macOS/Windows) | Code Coverage |
|---|---|---|---|
 |
 |
Microsoft Python Language Server is located in its own repo Contributing to Microsoft Python Language Server
- Node.js (>= 8.9.1, < 9.0.0)
- Python 2.7 or later (required only for testing the extension and running unit tests)
- Windows, macOS, or Linux
- Visual Studio Code
- Following VS Code extensions:
- Have an issue which has been accepted with a "needs PR" label (feel free to indicate you would be happy to provide a PR for the issue)
git clone https://github.com/microsoft/vscode-python
cd vscode-python
npm install
python3 -m venv .venv
# Activate the virtual environment as appropriate for your shell.
python3 -m pip --disable-pip-version-check install -t ./pythonFiles/lib/python --no-cache-dir --implementation py --no-deps --upgrade -r requirements.txt
# Specifying the virtual environment simply varies between shells.
export CI_PYTHON_PATH=`pwd`/.venv/bin/pythonYou may see warnings that The engine "vscode" appears to be invalid., you can ignore these.
Run the Compile and Hygiene build Tasks from the Command Palette (short cut CTRL+SHIFT+B or ⇧⌘B)
You can also compile from the command-line:
tsc -p ./ # full compile
tsc --watch -p ./ # incrementalSometimes you will need to run npm run clean and even rm -r out.
This is especially true if you have added or removed files.
TypeScript errors and warnings will be displayed in the Problems window of Visual Studio Code:
To test the changes you launch a development version of VS Code on the workspace vscode, which you are currently editing.
Use the Launch Extension launch option.
- Ensure you have disabled breaking into 'Uncaught Exceptions' when running the Unit Tests
- For the linters and formatters tests to pass successfully, you will need to have those corresponding Python libraries installed locally
- Run the Tests via the
Debug Unit Testslaunch options.
You can also run them from the command-line (after compiling):
npm run test:unittests # runs all unit tests
npm run test:unittests -- --grep='<NAME-OF-SUITE>'To run only a specific test suite for unit tests:
Alter the launch.json file in the "Debug Unit Tests" section by setting the grep field:
"args": [
"--timeout=60000",
"--grep=[The suite name of your unit test file]"
],...this will only run the suite with the tests you care about during a test run (be sure to set the debugger to run the Debug Unit Tests launcher).
- Ensure you have disabled breaking into 'Uncaught Exceptions' when running the Unit Tests
- For the linters and formatters tests to pass successfully, you will need to have those corresponding Python libraries installed locally
- Run the Tests via the
Launch TestandLaunch Multiroot Testslaunch options. - Note you will be running tests under the default Python interpreter for the system.
Change the version of python the tests are executed with by setting the CI_PYTHON_PATH.
Tests will be executed using the system default interpreter (whatever that is for your local machine), unless you explicitly set the CI_PYTHON_PATH environment variable. To test against different versions of Python you must use this.
In the launch.json file, you can add the following to the Launch Tests setting to easily change the interpreter used during testing:
"env":{
"CI_PYTHON_PATH": "/path/to/interpreter/of/choice/python"
}You can also run them from the command-line (after compiling):
npm run testSingleWorkspace # will launch the VSC UI
npm run testMultiWorkspace # will launch the VSC UI...note this will use the Python interpreter that your current shell is making use of, no need to set CI_PYTHON_PATH here.
To limit system tests to a specific suite
If you are running system tests (we call them system tests, others call them integration or otherwise) and you wish to run a specific test suite, edit the src/test/index.ts file here:
...and identify the test suite you want to run/debug like this:
const grep = '[The suite name of your *test.ts file]'; // IS_CI_SERVER &&......and then use the Launch Tests debugger launcher. This will run only the suite you name in the grep.
And be sure to escape any grep-sensitive characters in your suite name (and to remove the change from src/test/index.ts before you submit).
Clone the repo into any directory, open that directory in VSCode, and use the Launch Extension launch option within VSCode.
The easiest way to debug the Python Debugger (in our opinion) is to clone this git repo directory into your extensions directory.
From there use the Extension + Debugger launch option.
Information on our coding standards can be found here.
We have CI tests to ensure the code committed will adhere to the above coding standards. *You can run this locally by executing the command npx gulp precommit or use the precommit Task.
Messages displayed to the user must ve localized using/created constants from/in the localize.ts file.
To effectively contribute to this extension, it helps to know how its development process works. That way you know not only why the project maintainers do what they do to keep this project running smoothly, but it allows you to help out by noticing when a step is missed or to learn in case someday you become a project maintainer as well!
First and foremost, we try to be helpful to users of the extension. We monitor Stack Overflow questions to see where people might need help. We also try to respond to all issues in some way in a timely manner (typically in less than one business day, definitely no more than a week). We also answer questions that reach us in other ways, e.g. Twitter.
The extension aims to do a new release every month. A release plan is created for each release to help track anything that requires a person to do (long term this project aims to automate as much of the development process as possible). The current issues being worked on for a release are tracked in a milestone (which is actively updated as plans change). All P0 are expected to be fixed in a milestone, else the release will be blocked. P1 issues are a top-priority in a milestone, but if they are not completed they will not block a milestone. All other issues are considered best-effort for that milestone.
The overall schedule is to release the same week as VS Code. We do bugfix-only releases between scheduled releases as necessary, but otherwise we aim to do one release a month.
All development is actively done in the master branch of the
repository. It is what allows us to have a
development build which is expected to be stable at
all times. We do keep the most recent release as a branch in case the
need for a bugfix release arises. But once a new release is made we
delete the older release branch (all releases are appropriately
tagged, so no history is lost).
To help actively track what stage issues are at, various labels are used. The following label types are expected to be set on all open issues (otherwise the issue is not considered triaged):
needsfeaturetype
These labels cover what is blocking the issue from closing, what is affected by
the issue, and what kind of issue it is. Typically, on new issues, the needs label is either needs verification or needs more info. The feature label should be feature-* if the issue doesn't fit into any other feature label appropriately.
It is also very important to make the title accurate. People often write very brief, quick titles or ones that describe what they think the problem is. By updating the title to be appropriately descriptive for what you think the issue is, you not only make finding older issues easier, but you also help make sure that you and the original reporter agree on what the issue is.
Once an issue has been appropriately classified, there are two keys ways to help out. One is to go through open issues that needs verification. Issues with this label have not been verified to be an actual problem (e.g. making sure the reported issue is not caused by the user's configuration or machine).
The other way to help is to go through issues that are labeled as validate fix. These issues are believed to be fixed, but having an independent validation is always appreciated.
If a closed issue is labeled with "volunteer" that means the development team has no plans to implement the work for the issue, but that we would accept a pull request if provided. We close these types of issues to help us stay focused on the issues we do plan/hope to get to (which we will also accept pull requests for, just please discuss design considerations with us first to help make sure your pull request will be accepted).
Key details that all pull requests are expected to handle should be in the pull request template. We do expect CI to be passing for a pull request before we will consider merging it.
Starting in 2018, the extension switched to
calendar versioning since the extension
auto-updates and thus there is no need to track its version
number for backwards-compatibility. As such, the major version
is the current year, the minor version is the month when feature
freeze was reached, and the micro version is how many releases there
have been since that feature freeze (starting at 0). For example
the release made when we reach feature freeze in July 2018
would be 2018.7.0, and if a second release was necessary to fix a
critical bug it would be 2018.7.1.
Overall steps for releasing are covered in the release plan (template).
To create a release build, follow the steps outlined in the release plan (which has a template).
We publish the latest development build of the extension onto a cloud storage provider. If you are interested in helping us test our development builds or would like to stay ahead of the curve, then please feel free to download and install the extension from the following location. Once you have downloaded the ms-python-insiders.vsix file, please follow the instructions on this page to install the extension.
The development build of the extension:
- Will be replaced with new releases published onto the VS Code Marketplace.
- Does not get updated with new development builds of the extension (if you want to test a newer development build, uninstall the old version of the extension and then install the new version)
- Is built everytime a PR is commited into the
masterbranch.
If you would like to have a copy of the extension installed from a git clone so it can be refreshed regularly, the pvsc-dev-ext.py script will help facilitate that. The script provides two commands.
To create the git clone and do the initial build, use the setup command:
$ python3 pvsc-dev-ext.py setup stable
You may choose to have the script set up either a stable or insiders install of VS Code.
Once the extension is set up with a dev install, you can update it at any time to match what is in the master branch by using the update command:
$ python3 pvsc-dev-ext.py update
This will update stable and/or insiders installs of the extension. You can run this command at e.g. startup of your computer to make sure you are always using the latest version of the extension in VS Code.