Contributing

Development environment

(If using mamba/conda, could use e.g. mamba create --name vc_dev python=3.10)

git clone https://github.com/ESA-VirES/VirES-Python-Client
pip install -e VirES-Python-Client/[dev]

(beware that this will install nox, which you may not want)

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 one of:
  • cd docs; make clean; make html; firefox _build/html/index.html & (if you have sphinx installed and other deps in pyproject.toml - which can be obtained with pip install -e .[docs])
  • Using nox: nox -s docs
  • Using sphinx-autobuild

    pip install sphinx-autobuild
    sphinx-autobuild docs docs/_build/html
    

Testing

• Use pytest framework
• ... todo

Packaging & distribution

Published on PyPI and conda-forge:

1. The pip package is automatically built and pushed to PyPI when a release is made on GitHub.
   See https://github.com/ESA-VirES/VirES-Python-Client/blob/master/.github/workflows/publish.yml
2. The conda-forge package will be built from the package on PyPI after a few hours through a PR opened automatically at https://github.com/conda-forge/viresclient-feedstock/

Instructions for pushing a new release:

1. Test locally...
   • Check tests with pytest and docs as above
   • Check that correct version number is in src/viresclient/__init__.py
   • Check that an entry is made in docs/release_notes.rst
2. Open PR:
   • a) from feature branch to staging
   • b) from hotfix branch to master
3. Check and merge PR:
   • GitHub Actions results should be green
   • Check docs build at https://viresclient.readthedocs.io
   • If all good: Merge staging branch to master
4. Go to https://github.com/ESA-VirES/VirES-Python-Client/releases
   • Tag with e.g. v0.4.0 and make release
   • Check the Action completes:
     https://github.com/ESA-VirES/VirES-Python-Client/actions/workflows/publish.yml
   • Check the release on PyPI: https://pypi.org/project/viresclient/#history
     and wait for the PR on the conda-forge feedstock
5. 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
6. Check zenodo entry: https://doi.org/10.5281/zenodo.2554162