Contributing to plotly.js
Please read the issue guidelines.
Making pull requests
Please read the pull request guidelines.
We use the following labels to track issues and PRs:
||bug report confirmed by a plotly team member|
||planned feature additions|
||performance related tasks|
||source code cleanup resulting in no enhancement for users|
||API doc or attribute description improvements|
||issue left open for community input and pull requests|
||Issue or PR that required discussion among maintaners before moving forward|
||PRs that required some intial feedback but not ready to merge|
||PRs that are completed from the author's perspective|
||PRs that are put on hold|
- node.js. We recommend using node.js v6.x or v4.x (both LTS).
Upgrading and managing node versions can be easily done using
nvmor its Windows alternatives.
Step 1: Clone the plotly.js repo and install its dependencies
git clone https://github.com/plotly/plotly.js.git cd plotly.js npm install
Step 2: Setup test environment
npm run pretest
Step 3: Start the test dashboard
This command bundles up the source files with source maps using browserify, starts a watchify file watcher (making the your dev plotly.js bundle update every time a source file is saved) and opens up a tab in your browser.
Step 4: Open up the console and start developing
A typical workflow is to make some modifications to the source, update the
test dashboard, inspect and debug the changes, then repeat. The test dashboard
comes bundled with some useful tools while developing - all bundled under the
||Creates a fresh graph div and returns it (default id of
||Returns the default or specified graph div.|
||Plots the specified mock (
||Creates a png snapshot of the plot and places it below.|
||Reloads the plotly.js script and will execute
||By default, set to
||Destroys all plots.|
View the source for more info.
Three additional helpers exist that are refreshed every second:
gd- this is the default plot div
fullData- shortcut to
fullLayout- shortcut to
There is also a search bar in the top right of the dashboard. This fuzzy-searches image mocks based on their file name and trace type.
Other npm scripts
npm run preprocess: pre-processes the css and svg source file in js. This script must be run manually when updating the css and svg source files.
npm run watch: starts a watchify file watcher just like the test dashboard but without booting up a server.
Both jasmine and image tests are run on CircleCI on every push to this repo.
Jasmine tests are run in a browser using karma. To run them locally:
npm run test-jasmine
To run a specific suite, use:
npm run test-jasmine -- tests/<suite>.js
<suite> corresponds to the suite's file name as found in
test/jasmine/tests/. In certain situations, you may find that the default reporting is not verbose enough to pin down the source of the failing test. In this situation, you may wish to use karma-verbose-reporter. You can use it without adding as a dev dependency by running:
npm install karma-verbose-reporter
reporters: ['verbose'] to the corresponding karma configuration file. (You should disable the
progress reporter when using
Image pixel comparison tests are run in a docker container. For more information on how to run them locally, please refer to image test README.
Running the test locally outputs the generated png images in
build/test_images/ and the png diffs in
build/test_images_diff/ (two git-ignored directories).
To view the image pixel comparison test results, run
npm run start-image_viewer
which shows the baseline image, the generated image, the diff and the json mocks of test cases that failed.
To view the results of a run on CircleCI, download the
build/test_images_diff/ artifacts into your local repo and then run
npm run start-image_viewer.
- Distributed files are in
- CommonJS require-able modules are in
- Sources files are in
src/, including the index
- Build and repo management scripts are in
- All tasks can be run using
- Tests are
test/, they are partitioned into
- Test dashboard and image viewer code is in
- Non-distributed, built files are in
build/(most files in here are git-ignored, the css and font built files are exceptions)
Check if ok, with
npm run lint