Glad that you decided to make your contribution in Dash, to set up your development environment, run the following commands:
# in your working directory
$ git clone https://github.com/plotly/dash
$ cd dash
$ python3 -m venv .venv/dev
# activate the virtualenv
# on windows `.venv\dev\scripts\activate`
# on some linux / mac environments, use `.` instead of `source`
$ source .venv/dev/bin/activate
# install dash and dependencies
$ pip install -e .[testing,dev] # in some shells you need \ to escape []
$ cd dash-renderer
# build renderer bundles, this will build all bundles from source code
# the only true source of npm version is defined in package.json
$ npm install
$ npm run build # or `renderer build`
# install dash-renderer for development
$ pip install -e .
# build and install components used in tests
$ cd .. # should be back in dash/ root directory
$ npm install
$ npm run setup-tests.py # or npm run setup-tests.R
# you should see both dash and dash-renderer are pointed to local source repos
$ pip list | grep dash
Dash Renderer
began as a separate repository. It was merged into the main Dash
repository as part of the 1.0 release. It is the common frontend for all Dash backends (R and Python), and manages React Component layout and backend event handling.
If you want to contribute or simply dig deeper into Dash, we encourage you to play and taste it. This is the most efficient way to learn and understand everything under the hood.
For contributors with a primarily Python or R background, this section might help you understand more details about developing and debugging in JavaScript world.
As of Dash 1.2, the renderer bundle and its peer dependencies can be packed and generated from the source code. The dash-renderer\package.json
file is the one version of the truth for dash renderer version and npm dependencies. A build tool renderer
, which is a tiny Python script installed by Dash as a command-line tool, has a few commands:
renderer clean
deletes all the previously generated assets by this same tool.renderer npm
installs all the npm modules using thispackage.json
files. Note that thepackage-lock.json
file is the computed reference product for the versions defined with tilde(~) or caret(^) syntax in npm.renderer bundles
parses the locked version JSON, copies all the peer dependencies into dash_renderer folder, bundles the renderer assets, and generates an__init__.py
to map all the resources. There are also a list of helpfulscripts
property defined inpackage.json
you might need to do some handy tasks like linting, syntax format with prettier, etc.renderer digest
computes the content hash of each asset indash_renderer
folder, prints out the result in logs, and dumps into a JSON filedigest.json
. Use this when you have a doubt about the current assets indash_renderer
, and compare it with previous result in one shot by this command.renderer build
runs 1, 2, 3, 4 in sequence as a complete build process from scratch.renderer build local
runs the same order as in 5 and also generates source maps for debugging purposes. You also need to install dash-renderer with editable mode:pip install -e .
.
When a change in renderer code doesn't reflect in your browser as expected, this could be: confused bundle generation, caching issue in a browser, Python package not in editable
mode, etc. The new tool reduces the risk of bundle assets by adding the digest to help compare asset changes.
Writing Python 2/3 compatible code might be a challenging task for contributors used to working on one particular version, especially new learners who start directly with Python 3.
We use python-future
as our tool to mainly write Python 3 code and make it back-compatible to Python 2.7 (the only Python 2 version Dash supports). Please refer to this list of idioms for more details on working with python-future
.
Use the GitHub flow when proposing contributions to this repository (i.e. create a feature branch and submit a PR against the default branch).
For pull request with notable file changes or a big feature development, we highly recommend to organize the commits in a logical manner, so it
- makes a code review experience much more pleasant
- facilitates a possible cherry picking with granular commits
an intuitive example is worth a thousand words.
Git command veterans might argue that a simple terminal and a cherry switch keyboard is the most elegant solution. But in general, a desktop tool makes the task easier.
Plotlyers love to use emoji as an effective communication medium for
Commit Messages
Emojis make the commit messages 🌸. If you have no idea about what to add ? Here is a nice cheatsheet and just be creative!
Code Review Comments
- 💃
:dancer:
- used to indicate you can merge! Equivalent to GitHub's :squirrel: - 🐄
:cow2:
cow tip - minor coding style or code flow point - 🐅
:tiger2:
testing tiger - something needs more tests, or tests need to be improved - 🐍
:snake:
security snake - known or suspected security flaw - 🐐
:goat:
grammar goat - 😸
:smile_cat:
happy cat - for bits of code that you really like! - 🎎
:dolls:
documentation dolls - 💊
:pill:
performance enhancing pill - 🔪
:hocho:
removal of large chunks of code (obsolete stuff, or feature removals) - 🐛
:bug:
- a bug of some kind. 8 legged or 6. Sometimes poisonous. - 🐫 🌴
:camel:
:palm_tree:
- The Don't Repeat Yourself (DRY) camel or palm tree. - 👾
:space_invader:
- Too much space or too little. - 🍝
:spaghetti:
- copy-pasta, used to signal code that was copy-pasted without being updated
We use flake8
, pylint
, and black
for linting. please refer to the relevant steps in .circleci/config.yml
.
Our tests use Google Chrome via Selenium. You will need to install ChromeDriver matching the version of Chrome installed on your system. Here are some helpful tips for Mac and Windows.
We use pytest as our test automation framework, plus jest for a few renderer unit tests. You can npm run test
to run them all, but this command simply runs pytest
with no arguments, then cd dash-renderer && npm run test
for the renderer unit tests.
Most of the time, however, you will want to just run a few relevant tests and let CI run the whole suite. pytest
lets you specify a directory or file to run tests from (eg pytest tests/unit
) or a part of the test case name using -k
- for example pytest -k cbcx004
will run a single test, or pytest -k cbcx
will run that whole file. See the testing tutorial to learn about the test case ID convention we use.
For simple API changes, please add adequate unit tests under /tests/unit
Note: You might find out that we have more integration tests than unit tests in Dash. This doesn't mean unit tests are not important, the test pyramid is still valid. Dash project has its unique traits which needs more integration coverage than typical software project, another reason was that dash was a quick prototype crafted by chris in a lovely montreal summer.
We introduced the dash.testing
feature in Dash 1.0. It makes writing a Dash integration test much easier. Please read the tutorial and add relevant integration tests with any new features or bug fixes.
Dash, and many of Plotly's open source products, have been funded through direct sponsorship by companies. Get in touch about funding feature additions, consulting, or custom app development.