Contributing

Read this if you want to contribute. Some ideas for what needs doing, and guidelines on how to do it. The first port of call should be the issue tracker, where more pressing specific issues are listed, and where you can make your own bug reports and feature requests.

---

Notebooks

• Refer to https://github.com/Swarm-DISC/Swarm_notebooks

---

Documentation

• docs are generated by sphinx on readthedocs from .rst files
• API documentation is automatically built from the docstrings
• Use Google-style docstrings: https://sphinxcontrib-napoleon.readthedocs.io/en/latest/example_google.html
  • (these are processed by the sphinx ext module napoleon)
• Check docs locally with cd docs; make clean; make html; firefox _build/html/index.html &
  • Requires some things: conda install nbsphinx sphinx_rtd_theme
  • PDF creation is broken because of some Latex stuff in the example notebook

---

Testing

• Use pytest for testing
• There are some unit tests but not many, so this should be extended
• We need some automatic integration testing
  • Write tests that fetch all the data for a day and check that they can be converted to pandas/xarray and have some sensible output (maybe one test for each collection, with separate tests to check behaviour when fetching models)
  • To do this on Travis, then either need to whitelist the Travis IP addresses, or do the authentication like this: https://docs.travis-ci.com/user/encryption-keys/
    • The authentication method will be changing soon so I'll wait on that

---

Overview of viresclient structure

• [missing]
• Would be useful to make a class dependency diagram

---

Packaging & distribution

Currently on PyPI. I would also like to distribute on conda (this will require putting cdflib on conda too).

Instructions for pushing a new release (only I can do the pyPI at the moment):

1. Test locally...
   • Check tests with pytest
   • Local pip editable pip install: pip install -e .
   • Check docs with cd docs; make clean; make html; firefox _build/html/index.html &
2. Make commits and git push
   • Check installation and tests on Travis-CI
   • Check latest docs build at https://viresclient.readthedocs.io
   • Check version number (remove -alpha) in viresclient/__init__.py
3. Go to https://github.com/ESA-VirES/VirES-Python-Client/releases
   • Tag with e.g. v0.4.0
   • Make release
4. Build package with python setup.py sdist bdist_wheel
5. Upload to pypi with twine upload dist/*
6. Increment version number in __init__.py so that new commits go on the next version number
   • Append -alpha to the version number (e.g. 0.5.0-alpha) to indicate pre-release
7. Check zenodo entry: https://doi.org/10.5281/zenodo.2554162