|
| 1 | +# Contributing to dash |
| 2 | + |
| 3 | +## Getting Started |
| 4 | + |
| 5 | +Refer to the [readme](README.md) for installation and development instructions. |
| 6 | + |
| 7 | +## Coding Style |
| 8 | + |
| 9 | +Please lint any additions to Python code with `pylint` and `flake8`. |
| 10 | + |
| 11 | +## Pull Request Guidelines |
| 12 | + |
| 13 | +Use the [GitHub flow][] when proposing contributions to this repository (i.e. create a feature branch and submit a PR against the master branch). |
| 14 | + |
| 15 | +## Running the Tests |
| 16 | + |
| 17 | +**Warning:** _Tests do not currently run on windows. Track our progress: [#409](https://github.com/plotly/dash/issues/409)._ |
| 18 | + |
| 19 | +To run the tests, you can use Python's `unittest` module, or a test runner like `nose2`. |
| 20 | + |
| 21 | +To run all of the tests: |
| 22 | +`python -m unittest tests` |
| 23 | + |
| 24 | +Or: |
| 25 | +`nose2 -v` |
| 26 | + |
| 27 | +## Local configuration |
| 28 | +You can configure the test server with the following variables: |
| 29 | +### DASH_TEST_CHROMEPATH |
| 30 | +If you run a special chrome set the path to your chrome binary with this environment variable. |
| 31 | + |
| 32 | +### DASH_TEST_PROCESSES |
| 33 | +If you encounter errors about Multi-server + Multi-processing when running under Python 3 try running the tests with the number of server processes set to 1. |
| 34 | + |
| 35 | +### Example: single test run with configuration |
| 36 | +``` |
| 37 | +DASH_TEST_CHROMEPATH=/bin/google-chrome-beta DASH_TEST_PROCESSES=1 python -m unittest -v test.test_integration.Tests.test_inputs |
| 38 | +``` |
| 39 | + |
| 40 | +## Making a contribution |
| 41 | +_For larger features, your contribution will have a higher likelihood of getting merged if you create an issue to discuss the changes that you'd like to make before you create a pull request._ |
| 42 | + |
| 43 | +1. Create a pull request and tag the Plotly team (`@plotly/dash`) and tag / request review from [@rmarren1](https://github.com/rmarren1) and [@T4rk1n](https://github.com/T4rk1n). |
| 44 | +2. 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 create a prerelease: |
| 45 | + * Add `rc1` to `version.py` (`./dash/version.py`) e.g. `0.13.0rc1` |
| 46 | + - If needed, ask @chriddyp to get PyPi package publishing access. |
| 47 | + * Run `python setup.py sdist` to build a distribution zip. |
| 48 | + * Check the `dist` folder for a `tar.gz` file ending with your selected version number. Double check that this version number ends with `rc#`, as to not mistakenly publish the package. |
| 49 | + * Run `twine upload dist/<package_name>`. |
| 50 | +3. Comment in the PR with the prerelease version |
| 51 | +4. Update the top-level comment to include info about how to install, a summary of the changes, and a simple example. |
| 52 | + * This makes it easier for a community member to come in and try it out. As more folks review, it's harder to find the installation instructions deep in the PR |
| 53 | + * Keep this top-level comment updated with installation instructions (e.g. the `pip install` command) |
| 54 | +5. Make a post in the [Dash Community Forum][] |
| 55 | + * Title it `":mega: Announcement! New <Your Feature> - Feedback Welcome"` |
| 56 | + * In the description, link to the PR and any relevant issue(s) |
| 57 | + * Pin the topic so that it appears at the top of the forum for two weeks |
| 58 | + |
| 59 | +## [Checklists](http://rs.io/unreasonable-effectiveness-of-checklists/) |
| 60 | +### Pre-Merge checklist |
| 61 | +- [ ] All tests on CircleCI have passed. |
| 62 | +- [ ] All visual regression differences have been approved. |
| 63 | +- [ ] If changes are significant, a release candidate has been created and posted to Slack, the Plotly forums, and at the very top of the pull request. |
| 64 | +- [ ] You have updated the `dash/version.py` file and the top of `CHANGELOG.md`. For larger additions, your `CHANGELOG.md` entry includes sample code about how the feature works. The entry should also link to the original pull request(s). |
| 65 | +- [ ] Two people have :dancer:'d the pull request. You can be one of these people if you are a Dash core contributor. |
| 66 | + |
| 67 | +### Post-Merge checklist |
| 68 | +- [ ] You have tagged the release using `git tag v<version_number>`. |
| 69 | + |
| 70 | +### Pre-Release checklist |
| 71 | +- [ ] Everything in the Pre-Merge checklist is completed. (Except the last two if this is a release candidate). |
| 72 | +- [ ] `git remote show origin` shows you are in the correct repository. |
| 73 | +- [ ] `git branch` shows that you are on the expected branch. |
| 74 | +- [ ] `git status` shows that there are no unexpected changes. |
| 75 | +- [ ] `dash/version.py` is at the correct version. |
| 76 | + |
| 77 | +### Post-Release checklist |
| 78 | +- [ ] You have closed all issues that this pull request solves, and commented the new version number users should install. |
| 79 | +- [ ] You have created an issue about documenting the new feature or change and you have added it to the [Documentation] project. |
| 80 | +- [ ] You have created a pull request in `dash-docs` with the new release of your feature by editing that project's [`requirements.txt` file](https://github.com/plotly/dash-docs/blob/master/requirements.txt) and you have assigned `@chriddyp` to review. |
| 81 | + |
| 82 | +## Financial Contributions |
| 83 | + |
| 84 | +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. |
| 85 | + |
| 86 | +[Dash Core Components]: https://dash.plot.ly/dash-core-components |
| 87 | +[Dash HTML Components]: https://github.com/plotly/dash-html-components |
| 88 | +[write your own components]: https://dash.plot.ly/plugins |
| 89 | +[Dash Component Biolerplate]: https://github.com/plotly/dash-component-boilerplate |
| 90 | +[issues]: https://github.com/plotly/dash-core-components/issues |
| 91 | +[GitHub flow]: https://guides.github.com/introduction/flow/ |
| 92 | +[eslintrc-react.json]: https://github.com/plotly/dash-components-archetype/blob/master/config/eslint/eslintrc-react.json |
| 93 | +[contributors]: https://github.com/plotly/dash-core-components/graphs/contributors |
| 94 | +[semantic versioning]: https://semver.org/ |
| 95 | +[Dash Community Forum]: https://community.plot.ly/c/dash |
| 96 | +[Confirmation Modal component]: https://github.com/plotly/dash-core-components/pull/211#issue-195280462 |
| 97 | +[Confirmation Modal announcement]: https://community.plot.ly/t/announcing-dash-confirmation-modal-feedback-welcome/11627 |
| 98 | +[Get in touch]: https://plot.ly/products/consulting-and-oem |
| 99 | +[Documentation]: https://github.com/orgs/plotly/projects/8 |
0 commit comments