Thank you for your interesting in contributing to this open-source project! Make sure that you have read and understood our code of conduct.
Please follow the following steps for local testing:
- Clone the repo
git clone https://github.com/plotly/dash-cytoscape.git
- In order to run the Python builds (
npm run build:backends
) you need to create a venv for this project. Make sure you havevirtualenv
correctly installed and run this:
mkdir dash_cytoscape_dev
cd dash_cytoscape_dev
virtualenv venv # Create a virtual env
source venv/bin/activate # Activate the venv
pip install -r requirements.txt # Install the requirements
To activate in windows, replace the 4th line with this:
venv\Scripts\activate
- Install the JavaScript dependencies and build the code:
npm install
npm run build:backends
Before v0.2.0, our preferred package manager for this project is Yarn. Starting with v0.2.0, we will be using npm
in order to create less confusion and ensure a unified package manager with other Dash components. Therefore we use package-lock.json
rather than yarn.lock.
. If you are contributing a PR to dash-cytoscape, we encourage you to also use npm
.
Please lint any additions to Python code with pylint
and flake8
:
flake8 --max-line-length=100 usage.py usage-advanced.py usage-elements.py usage-events.py usage-stylesheet.py
flake8 --max-line-length=100 demos tests
pylint usage.py usage-advanced.py usage-elements.py usage-events.py usage-stylesheet.py
pylint demos tests
-
Is your code clear? If you had to go back to it in a month, would you be happy to? If someone else had to contribute to it, would they be able to?
A few suggestions:
-
Make your variable names descriptive and use the same naming conventions throughout the code.
-
For more complex pieces of logic, consider putting a comment, and maybe an example.
-
In the comments, focus on describing why the code does what it does, rather than describing what it does. The reader can most likely read the code, but not necessarily understand why it was necessary.
-
Don't overdo it in the comments. The code should be clear enough to speak for itself. Stale comments that no longer reflect the intent of the code can hurt code comprehension.
-
- Don't repeat yourself. Any time you see that the same piece of logic can be applied in multiple places, factor it out into a function, or variable, and reuse that code.
- Scan your code for expensive operations (large computations, DOM queries, React re-renders). Have you done your possible to limit their impact? If not, it is going to slow your app down.
- Can you think of cases where your current code will break? How are you handling errors? Should the user see them as notifications? Should your app try to auto-correct them for them?
Activate your virtualenv:
source venv/bin/activate
If needed, install the requirements:
pip install -r tests/requirements.txt
Run the following tests:
python -m unittest tests.test_callbacks
python -m unittest tests.test_interactions
python -m unittest tests.test_usage
Look inside the tests/screenshots
directory to find the images created by the tests. If you have
Percy configured, run the following test:
python -m unittest tests.test_percy_snapshot
Make sure to configure your Percy environment variables correctly:
PERCY_BRANCH=local
PERCY_ENABLED=1
PERCY_TOKEN=***************
You can find the token in the project settings of the Percy project. Only members of the Plotly organizations have access to this token.
The tests are broken down in 3 categories:
- Callbacks: Tests if the
elements
,stylesheet
andlayout
properties can be updated correctly by other Dash components using callbacks. - Interactions: Tests user interactions such as dragging, clicking, and hovering over nodes, as well as the associated event callbacks.
- Usage: Tests if all of the usage apps render correctly on start. This does not test callbacks.
Those tests are rendered into images located inside tests/screenshots
, which are then sent to a Percy build using tests.test_percy_snapshot
, which creates a Dash app that only serves the content of tests/screenshots
at different routes, which are then captured by the Percy runner.
Create a pull request and tag the Plotly team (@plotly/dash-core
) and tag / request review from @xhlulu.
After a review has been done and your changes have been approved, create a prerelease and comment in the PR. Version numbers should follow semantic versioning.
To publish or create a prerelease:
- Check
MANIFEST.in
has all of the extra files (like CSS) - Bump version numbers in
package.json
, update the CHANGELOG, and make a pull request - Once the pull request is merged into master:
- Build
npm run build:backends
- Create distribution tarball
python setup.py sdist
- Copy the tarball into a separate folder and try to install it and run the examples:
cp dist/dash_cytoscape-x.x.x.tar.gz ../temp
cp usage.py ../temp
cd ../temp
source venv/bin/activate
pip install dash_cytoscape-x.x.x.tar.gz
python usage.py
- If the examples work, then publish:
npm publish
twine upload dist/dash_cytoscape-x.x.x.tar.gz
- Tag your release with git:
git tag -a 'vx.x.x' -m 'vx.x.x'
git push origin master --follow-tags
- Verify that the publish worked by installing it:
cd ../temp
pip install dash-cytoscape==x.x.x
python usage.py
Make a post in the Dash Community Forum
- Title it
":mega: Announcement! New <Your Feature> - Feedback Welcome"
- In the description, link to the PR and any relevant issue(s)
- Pin the topic so that it appears at the top of the forum for two weeks
Beginner tip: Copy and paste this section as a comment in your PR, then check off the boxes as you go!
- The project was correctly built with
npm run build:backends
. - If there was any conflict, it was solved correctly
- All changes were documented in CHANGELOG.md.
- All tests on CircleCI have passed.
- All Percy visual changes have been approved.
- Two people have 💃'd the pull request. You can be one of these people if you are a Dash Cytoscape core contributor.
- Make sure to Squash and Merge your contribution if you have created multiple commits to change a specific feature.
- Make sure to Rebase and Merge if you added many different features, and need to contribute multiple different commits.
- You have tagged the release using
git tag v<version_number>
(for the contributor merging the PR). - You have pushed this tag using
git push <tag_name>
(for the contributor merging the PR). - You have deleted the branch.
- Everything in the Pre-Merge checklist is completed.
-
git remote show origin
shows you are in the correct repository. -
git branch
shows that you are on the expected branch. -
git status
shows that there are no unexpected changes. - Both
package.json
anddash_cytoscape/package.json
versions have been correctly updated.
Complete the "Publishing" section.
- Step 1 and 2 of Post-merge checklist are completed.
- You have closed all issues that this pull request solves, and commented the new version number users should install.
- If significant enough, you have created an issue about documenting the new feature or change and you have added it to the Documentation project.
- You have created a pull request in Dash Docs with the new release of your feature by editing that project's
requirements.txt
file.
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.