Skip to content

Latest commit

 

History

History
285 lines (200 loc) · 13.8 KB

CONTRIBUTING.md

File metadata and controls

285 lines (200 loc) · 13.8 KB
Raw

Contributing to the Python extension for Visual Studio Code

release branch master branch Nightly CI coverage (master branch)
Build Status Build Status Build Status codecov

[Development build]

[For contributing to the Microsoft Python Language Server see its own repo; for ptvsd see its own repo]

Contributing a pull request

Prerequisites

  1. Node.js 10.x
  2. Python 2.7 or later (required only for testing the extension and running unit tests)
  3. Windows, macOS, or Linux
  4. Visual Studio Code
  5. The following VS Code extensions:
  6. 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)

Setup

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.
npx gulp installPythonLibs
# If your terminal doesn't recogonise the keyword `python3`, update `launch.json` to set a value for the environment variable `CI_PYTHON_PATH` pointing to the fully qualified path of the above interpreter.

You may see warnings that The engine "vscode" appears to be invalid., you can ignore these.

Incremental Build

Run the Compile and Hygiene build Tasks from the Run Build Task... command picker (short cut CTRL+SHIFT+B or ⇧⌘B). This will leave build and hygiene tasks 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
npm run compile-webviews-watch # For data science (React Code)

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.

Errors and Warnings

TypeScript errors and warnings will be displayed in the Problems window of Visual Studio Code:

Validate your changes

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.

Debugging Unit Tests

  1. Ensure you have disabled breaking into 'Uncaught Exceptions' when running the Unit Tests
  2. For the linters and formatters tests to pass successfully, you will need to have those corresponding Python libraries installed locally
  3. Run the Tests via the Unit Tests launch option.

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", "<suite name>"
    ],

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

Debugging System Tests

  1. Ensure you have disabled breaking into 'Uncaught Exceptions' when running the Unit Tests
  2. For the linters and formatters tests to pass successfully, you will need to have those corresponding Python libraries installed locally by using the ./requirements.txt and build/test-requirements.txt files
  3. Run the tests via npm run or the Debugger launch options (you can "Start Without Debugging").
  4. 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 appropriate configuration you want to run to easily change the interpreter used during testing:

    "env":{
        "CI_PYTHON_PATH": "/absolute/path/to/interpreter/of/choice/python"
    }

You can also run the tests 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:

https://github.com/Microsoft/vscode-python/blob/b328ba12331ed34a267e32e77e3e4b1eff235c13/src/test/index.ts#L21

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

Testing Python Scripts

The extension has a number of scripts in ./pythonFiles. Tests for these scripts are found in ./pythonFiles/tests. To run those tests:

  • python2.7 pythonFiles/tests/run_all.py
  • python3 -m pythonFiles.tests

By default, functional tests are included. To exclude them:

python3 -m pythonFiles.tests --no-functional

To run only the functional tests:

python3 -m pythonFiles.tests --functional

Standard Debugging

Clone the repo into any directory, open that directory in VSCode, and use the Launch Extension launch option within VSCode.

Debugging the Python Extension Debugger

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.

Coding Standards

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.

Development process

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!

Helping others

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.

For pull requests, we aim to review any externally contributed PR no later than the next sprint from when it was submitted (see Release Cycle below for our sprint schedule).

Release cycle

Planning is done as two week sprints. We start a sprint every other Wednesday. You can look at the newest milestone to see when the current sprint ends. All P0 issues are expected to be fixed in the current sprint, else the next release will be blocked. P1 issues are a top-priority and we try to close before the next release. All other issues are considered best-effort for that sprint.

The extension aims to do a new release every four weeks (two sprints). 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).

All development is actively done in the master branch of the repository. This allows us to have a development build which is expected to be stable at all times. Once we reach a release candidate, it becomes our release branch. At that point only what is in the release branch will make it into the next release.

Issue triaging

Classifying issues

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):

  1. needs/triage/classify
  2. feature
  3. type

These labels cover what is blocking the issue from closing, what is affected by the issue, and what kind of issue it is. (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.

Post-classification

Once an issue has been appropriately classified, there are two keys ways to help out. One is to go through open issues that have a merged fix and verify that the fix did in fact work. The other is to try to fix issues marked as needs PR.

Pull requests

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.

Versioning

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 build number is a number that increments for every build. For example the release made when we reach feature freeze in July 2018 would be 2018.7.<some number>, and if there is a second release in that month it would be 2018.7.<some larger number>.

Releasing

Overall steps for releasing are covered in the release plan (template).

Building a release

To create a release build, follow the steps outlined in the release plan (which has a template).

Development Build

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 every time a PR is committed into the master branch.