The bottom line. Follow your Nose, or our Nose. Write-run-love tests ✊.
Check out the Code of Conduct. Don't tl:dr; it, but the general idea is to be nice.
Open an issue! Go to https://github.com/plotly/plotly.py/issues. It's possible that your issue was already addressed. If it wasn't, open it. We also accept PRs; take a look at the steps below for instructions on how to do this.
Check out our Support App: https://support.plot.ly/libraries/python or Community Forum: https://community.plot.ly/.
First, you'll need to get our project. This is the appropriate clone command (if you're unfamiliar with this process, https://help.github.com/articles/fork-a-repo):
DO THIS (in the directory where you want the repo to live)
git clone https://github.com/your_github_username/plotly.py.gitTODO: Use virtualenv or conda, activate it
http://docs.python-guide.org/en/latest/dev/virtualenvs/
$ pip install -r requirements.txt
$ pip install -r optional-requirements.txt
$ pip install -e packages/python/plotly/
$ pip install -e packages/python/chart-studio/
$ pip install -e packages/python/plotly-geo/
Run the following commands in your virtual environment to use the
development version of FigureWidget,
$ jupyter nbextension enable --py widgetsnbextension
$ jupyter nbextension install --py --symlink --sys-prefix plotlywidget
$ jupyter nbextension enable --py --sys-prefix plotlywidget
This project uses git submodules. They're both helpful and, at times, difficult to work with. The good news is you probably don't need to think about them! Just run the following shell command to make sure that your local repo is wired properly:
DO THIS (run this command in your new plotly.py directory)
python update_submodules.pyThat's going to initialize the submodules we use in this project, update them so that they're synced to the proper commit, and copy files to the appropriate locations in your local repo.
Here's what you need to know: changes to any files inside the following directories will get overwritten. These are synced with the submodules, if you need to change functionality there, you will need to make a pull request in the appropriate sub project repository.
packages/python/chart-studio/chart_studio/plotly/chunked_requestspackages/python/plotly/plotly/matplotlylib/mplexporter
This repo uses the Black code formatter,
and the pre-commit library to manage a git commit hook to
run Black prior to each commit. Both pre-commit and black are included in the
packages/python/plotly/optional-requirements.txt file, so you should have them
installed already if you've been following along.
To enable the Black formatting git hook, run the following from within your virtual environment.
(plotly_dev) $ pre-commit installNow, whenever you perform a commit, the Black formatter will run. If the formatter makes no changes, then the commit will proceed. But if the formatter does make changes, then the commit will abort. To proceed, stage the files that the formatter modified and commit again.
If you don't want to use pre-commit, then you can run black manually prior to making
a PR as follows.
(plotly_dev) $ black .Third, don't work in the master branch. As soon as you get your master branch ready, run:
DO THIS (but change the branch name)
git checkout -b my-dev-branch... where you should give your branch a more descriptive name than my-dev-branch
Once you've made your changes (and hopefully written some tests...), make that pull request!
First update the version of the plotly.js dependency in js/package.json.
Then run the updateplotlyjs command with:
$ python setup.py updateplotlyjsThis will download new versions of plot-schema.json and plotly.min.js from
the plotly/plotly.js GitHub repository (and place them in
plotly/package_data). It will then regenerate all of the graph_objs
classes based on the new schema.
We take advantage of two tools to run tests:
tox, which is both a virtualenv management and test tool.nose, which is is an extension of Python's unittest
Since our tests cover all the functionality, to prevent tons of errors from showing up and having to parse through a messy output, you'll need to install optional-requirements.txt as explained above.
After you've done that, go ahead and follow (y)our Nose!
nosetests -w packages/python/plotly/plotly/tests/Or for more verbose output:
nosetests -w packages/python/plotly/plotly/tests/ -vEither of those will run every test we've written for the Python API. You can get more granular by running something like:
nosetests -w packages/python/plotly/plotly/tests/test_core/... or even more granular by running something like:
nosetests plotly/tests/test_plotly/test_plot.pyRunning tests with tox is much more powerful, but requires a bit more setup.
You'll need to export an environment variable for each tox environment you wish to test with. For example, if you want to test with Python 2.7 and
Python 3.6, but only care to check the core specs, you would need to ensure that the following variables are exported:
export PLOTLY_TOX_PYTHON_27=<python binary>
export PLOTLY_TOX_PYTHON_36=<python binary>
Where the <python binary is going to be specific to your development setup. As a more complete example, you might have this loaded in a .bash_profile (or equivalent shell loader):
############
# tox envs #
############
export PLOTLY_TOX_PYTHON_27=python2.7
export PLOTLY_TOX_PYTHON_34=python3.4
export TOXENV=py27-core,py34-coreWhere TOXENV is the environment list you want to use when invoking tox from the command line. Note that the PLOTLY_TOX_* pattern is used to pass in variables for use in the tox.ini file. Though this is a little setup, intensive, you'll get the following benefits:
toxwill automatically manage a virtual env for each environment you want to test in.- You only have to run
toxand know that the module is working in bothPython 2andPython 3.
Finally, tox allows you to pass in additional command line arguments that are formatted in (by us) in the tox.ini file, see {posargs}. This is setup to help with our nose attr configuration. To run only tests that are not tagged with slow, you could use the following command:
tox -- -a '!slow'Note that anything after -- is substituted in for {posargs} in the tox.ini. For completeness, because it's reasonably confusing, if you want to force a match for multiple nose attr tags, you comma-separate the tags like so:
tox -- -a '!slow','!matplotlib'You're strongly encouraged to write tests that check your added functionality.
When you write a new test anywhere under the tests directory, if your PR gets accepted, that test will run in a virtual machine to ensure that future changes don't break your contributions!
Test accounts include: PythonTest, PlotlyImageTest, and PlotlyStageTest.
This is the release process for releasing plotly.py version X.Y.Z with
plotlywidget version A.B.C.
Note: The plotlywidget instructions must be followed if any change
has been made in the js/ directory source code, OR if the version of
plotly.js has been updated. If neither of these is the case, there's no need
to increment the plotlywidget version or to publish a new version to npm.
After all of the functionality for the release has been merged into master,
create a branch named release_X.Y.Z. This branch will become the
final version
Review the contents of packages/python/plotly/CHANGELOG.md. We try to follow
the keepachangelog guidelines.
Make sure the changelog includes the version being published at the top, along
with the expected publication date.
Use the Added, Changed, Deprecated, Removed, Fixed, and Security
labels for all changes to plotly.py. If the version of plotly.js has
been updated, include this as the first Updated entry. Call out any
noteable changes as sub-bullets (new trace types in particular), and provide
a link to the plotly.js CHANGELOG.
As the first entry in the changelog, include a JupyterLab Versions section.
Here, document the versions of plotlywidget,
@jupyter-widgets/jupyterlab-manager, jupyterlab, and
@jupyterlab/plotly-extension that are known to be compatible with this
version of plotly.py.
Note: Use the official (not release candidate) versions in the CHANGELOG.
Update the installation instructions in the README to the new versions of all
of the dependencies. Use the release candidate versions, this way we can point
people to the README of the release_X.Y.Z as the instructions for trying out
the release candidate.
Note that the conda installation instructions must include "-c plotly/lable/test" rather than "-c plotly" in order to install the release candidate version.
Commit Changelog and README updates.
- Manually update the plotlywidget version to
A.B.C-rc.1in the files specified below.
packages/python/plotly/plotly/_widget_version.py:- Update
__frontend_version__to^A.B.C-rc.1(Note the^prefix)
- Update
packages/javascript/plotlywidget/package.json- Update
"version"toA.B.C-rc.1
- Update
-
Commit the changes
-
Tag this commit on the release branch as
vX.Y.Zrc1andwidget-vA.B.C-rc.1
In both cases rc is the semantic versioning code for Release Candidate.
The number 1 means that this is the first release candidate, this number can
be incremented if we need to publish multiple release candidates.
Note that the npm suffix is -rc.1 and the PyPI suffix is rc1.
Publishing plotly.py and plotlywidget as release candidates
allows us to go through the publication process, and test that the
installed packages work properly before general users will get them by
default. It also gives us the opportunity to ask specific users to test
that their bug reports are in fact resolved before we pull the trigger
on the official release.
To upload to PyPI you'll also need to have twine installed:
(plotly_dev) $ pip install twineAnd, you'll need the credentials file ~/.pypirc. Request access from
@jonmmease and @chriddyp. Then, from inside the repository:
(plotly_dev) $ git checkout release_X.Y.Z
(plotly_dev) $ git stash
(plotly_dev) $ python setup.py sdist bdist_wheel
(plotly_dev) $ twine upload dist/plotly-X.Y.Zrc1*Now, publish the release candidate of the plotlywidget NPM package.
cd ./js
npm publish --access public --tag nextThe --tag next part ensures that users won't install this version unless
they explicitly ask for the version or for the version wtih the next tag.
To publish package to the plotly anaconda channel you'll need to have the
anaconda or miniconda distribution installed, and you'll need to have the
anaconda-client package installed.
(plotly_dev) $ conda build recipe/Next run anaconda login and enter the credentials for the plotly anaconda
channel.
Then upload artifacts to the anaconda channel using the test label. Using the test label will ensure that people will only download the release candidate version if they explicitly request it.
$ anaconda upload --label test /path/to/anaconda3/conda-bld/noarch/plotly-*.tar.bz2
Then logout with anaconda logout
Create a fresh virtual environment (or conda environment) and install
the release candidate by following the new README.md instructions
(the instructions updated above to include the release candidate versions)
Run through the example notebooks at
https://github.com/jonmmease/plotly_ipywidget_notebooks using the classic
notebook and JupyterLab. Make sure FigureWidget objects are displayed as
plotly figures, and make sure the in-place updates and callbacks work.
If appropriate, ask users who have submitted bug reports or feature requests that are resolved in this version to try out the release candidate.
If problems are found in the release candidate, fix them on the release branch and then publish another release candidate with the candidate number incremented.
Update CHANGELOG with release date and update README with final versions.
In the conda installation instructions, be sure to change the "-c plotly/label/test" argument to "-c plotly"
Commit updates.
When no problems are identified in the release candidate, remove the release candidate suffix from the following version strings:
plotly/_widget_version.py:- Update
__frontend_version__to^A.B.C(Note the^prefix)
- Update
js/package.json- Update
"version"toA.B.C
- Update
Commit and push to the release branch.
Make sure the integration tests are passing on the release branch, then merge it into master on GitHub.
Make sure tests also pass on master, then update your local master,
tag this merge commit as vX.Y.Z (e.g. v3.1.1) and widget-vA.B.C
push the tag.
(plotly_dev) $ git checkout master
(plotly_dev) $ git stash
(plotly_dev) $ git pull origin master
(plotly_dev) $ git tag vX.Y.Z
(plotly_dev) $ git push origin vX.Y.Z
(plotly_dev) $ git tag widget-vA.B.C
(plotly_dev) $ git push origin widget-vA.B.CPublish the final version to PyPI
(plotly_dev) $ cd packages/python/plotly
(plotly_dev) $ python setup.py sdist bdist_wheel
(plotly_dev) $ twine upload dist/plotly-X.Y.Z*After it has uploaded, move to another environment and double+triple check that you are able to upgrade ok:
$ pip install plotly --upgradeAnd ask one of your friends to do it too. Our tests should catch any issues, but you never know.
<3 Team Plotly
Finally, publish the final version of the widget library to npm with:
cd ./js
npm publish --access publicFollow the anaconda upload instructions as described for the release candidate above, except:
- Do not include the
--label testargument when uploading
$ anaconda upload /path/to/anaconda3/conda-bld/noarch/plotly-*.tar.bz2
Go to https://github.com/plotly/plotly.py/releases and "Draft a new release"
Enter the vX.Y.Z tag
Make "Release title" the same string as the tag.
Copy changelog section for this version as the "Describe this release"
Post a simple announcement to the Plotly Python forum, with links to the README installation instructions and to the CHANGELOG.
The plotly-geo package contains the shape file resources used by plotly.py.
These files are relatively large and change infrequently so it is useful
to release them in a separate package.
Update the version of the plotly-geo package in
packages/python/plotly-geo/setup.py.
This version is not intended to match the version of plotly.py.
Add a new entry to the CHANGELOG at packages/python/plotly-geo/CHANGELOG.md
and commit the changes.
Create a new tag for the release
(plotly_dev) $ git checkout master
(plotly_dev) $ git stash
(plotly_dev) $ git pull origin master
(plotly_dev) $ git tag plotly-geo-vX.Y.Z
(plotly_dev) $ git push origin plotly-geo-vX.Y.ZPublish the final version to PyPI
(plotly_dev) $ cd packages/python/plotly-geo
(plotly_dev) $ python setup.py sdist bdist_wheel
(plotly_dev) $ twine upload dist/plotly-geo-X.Y.Z.tar.gz
(plotly_dev) $ twine upload dist/plotly_geo-X.Y.Z-py3-none-any.whlFrom packages/python/plotly-geo, build the conda packge
(plotly_dev) $ conda build recipe/Then upload to the plotly anaconda channel as described above
The chart-studio package contains the utilities for interacting with
Chart Studio (both Cloud or On-Prem).
Update the version of the chart-studio package in
packages/python/chart-studio/setup.py.
This version is not intended to match the version of plotly.py.
Add a new entry to the CHANGELOG at packages/python/chart-studio/CHANGELOG.md
and commit the changes.
Create a new tag for the release
(plotly_dev) $ git checkout master
(plotly_dev) $ git stash
(plotly_dev) $ git pull origin master
(plotly_dev) $ git tag chart-studio-vX.Y.Z
(plotly_dev) $ git push origin chart-studio-vX.Y.ZPublish the final version to PyPI
(plotly_dev) $ cd packages/python/chart-studio
(plotly_dev) $ python setup.py sdist bdist_wheel
(plotly_dev) $ twine upload dist/chart-studio-X.Y.Z.tar.gz
(plotly_dev) $ twine upload dist/chart_studio-X.Y.Z-py3-none-any.whlFrom packages/python/plotly-geo, build the conda packge
(plotly_dev) $ conda build recipe/Then upload to the plotly anaconda channel as described above
If you are interested in contributing to the ever-growing Plotly figure factory library in Python, check out the documentation to learn how.