Skip to content

Latest commit

 

History

History
218 lines (171 loc) · 9.53 KB

CONTRIBUTING.md

File metadata and controls

218 lines (171 loc) · 9.53 KB
Raw

Contributing to Dash Cytoscape

Thank you for your interesting in contributing to this open-source project! Make sure that you have read and understood our code of conduct.

Setting up the environment

Please follow the following steps for local testing:

  1. Clone the repo
git clone https://github.com/plotly/dash-cytoscape.git
  1. In order to run the Python builds (npm run build:py) you need to create a venv for this project. Make sure you have virtualenv 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
  1. Install the JavaScript dependencies and build the code:
npm install
npm run build:all

Package manager

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.

Coding Style

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

Code quality & design

  • 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?

Tests

Running the tests

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

Percy

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.

About the tests

The tests are broken down in 3 categories:

  • Callbacks: Tests if the elements, stylesheet and layout 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.

Publishing

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:

  1. Check MANIFEST.in has all of the extra files (like CSS)
  2. Bump version numbers in package.json, update the CHANGELOG, and make a pull request
  3. Once the pull request is merged into master:
  4. Build
npm run build:all
  1. Create distribution tarball
python setup.py sdist
  1. 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
  1. If the examples work, then publish:
npm publish
twine upload dist/dash_cytoscape-x.x.x.tar.gz
  1. Tag your release with git:
git tag -a 'vx.x.x' -m 'vx.x.x'
git push origin master --follow-tags
  1. 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

Checklists

Beginner tip: Copy and paste this section as a comment in your PR, then check off the boxes as you go!

Pre-Merge checklist

  • The project was correctly built with npm run build:all.
  • 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.

Merge step

  1. Make sure to Squash and Merge your contribution if you have created multiple commits to change a specific feature.
  2. Make sure to Rebase and Merge if you added many different features, and need to contribute multiple different commits.

Post-Merge checklist

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

Pre-Release checklist

  • 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 and dash_cytoscape/package.json versions have been correctly updated.

Release Step

Complete the "Publishing" section.

Post-Release checklist

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

Financial Contributions

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.