Skip to content

contributing.md

Latest commit

 

History

History
87 lines (61 loc) · 3.97 KB

contributing.md

File metadata and controls

87 lines (61 loc) · 3.97 KB

How to Contribute

We would love to accept your patches and contributions to this project.

Before you begin

Sign our Contributor License Agreement

Contributions to this project must be accompanied by a Contributor License Agreement (CLA). You (or your employer) retain the copyright to your contribution; this simply gives us permission to use and redistribute your contributions as part of the project.

If you or your current employer have already signed the Google CLA (even if it was for a different project), you probably don't need to do it again.

Visit https://cla.developers.google.com/ to see your current agreements or to sign a new one.

Review our Community Guidelines

This project follows Google's Open Source Community Guidelines.

Contribution process

Prerequisites

  • VS Code
  • If using nvm (recommended): nvm use at repo root to set the correct versions of node and npm.
  • If not using nvm:
    • Node.js at the version listed in .nvmrc.
    • The matching npm version (comes bundled with node).
  • The following extensions:
  • Configure your environment:
    • Create an OAuth 2.0 Desktop client credentials (instructions).
    • Make a copy of the environment template: cp .env.template .env
    • Set the values in the .env file: 
      COLAB_EXTENSION_CLIENT_ID=<TODO>
COLAB_EXTENSION_CLIENT_NOT_SO_SECRET=<TODO>
    • Execute npm run generate:config to generate the required static config.

Local Development

  1. Open the repo root with VS Code.
  2. npm ci - install dependencies.
  3. npm run generate:config - generate the required static config. This only needs to be done when changes to .env are made.
  4. Launch the extension by pressing F5 or selecting Run Extension from VS Code's Run and Debug view.
  5. Create or open a Jupyter notebook file (.ipynb).
  6. Test and validate your changes.

Incremental Build

Launching the extension will automatically kick off the watch:prod build task. This can be ran without launching during development by running the build task.

Incremental build output can be found in the Terminal VS Code panel.

TypeScript errors and warnings can be found in the Problems VS Code panel, provided a typecheck-ing build is running (see package.json).

If you've removed files, you may need to npm run clean.

Tests

Unit tests must have the extension .unit.test.ts. To run them:

npm run test:unit
npm run test:unit -- --grep='your-regex-filter'

Unit tests can be debugged by launching Debug Unit Tests. The "args" can be modified to filter with the grep field as outlined above.

The unit tests rely extensively on a Sinon stub of the vscode module. vscode is the engine the Node app runs under and is not an installable npm package. While this stubbing is terse, it enables the entire unit test suite to run sub-1-second. Please peruse existing tests for reference when authoring new ones.

While there are end-to-end tests, running them requires access to accounts with automation exemptions that only Googlers can use. Pull request automation (once approved by a maintainer) will run them.

Code Reviews

All submissions, including submissions by project members, require review. We use GitHub pull requests for this purpose.