Development¶

Setup¶

For local development, install dependencies and an editable version of Pymagicc from a clone or download of the Pymagicc repository with

make venv
./venv/bin/pip install --editable .

Running the tests¶

To run the tests run

./venv/bin/pytest tests --verbose

To skip tests which run MAGICC and take longer use

./venv/bin/pytest tests --skip-slow

To get a test coverage report, run

./venv/bin/pytest --cov

Conventions¶

Style¶

To unify coding style, allowing us to focus more on writing useful code and less time worrying about formatting, black is used.

To format the files in pymagicc and tests as well as setup.py run

make black

Csvs¶

In our miscellaneous csv’s, for example the definitional csv’s, we follow the following conventions to make our lives easier:

column names are all lower case, with underscores as separators (i.e. no spaces)

Dependencies¶

A user of pymagicc should be able to pip install and run all of our notebooks. This means that all of the libraries for running notebooks should be explicit dependencies, rather than being included in an extras requirement. Whilst this means that we have more dependencies, it makes it easier for end users and avoids extremely cryptic import errors.

Building the documentation¶

The docs use Sphinx and can be rebuilt locally in docs/builds/html/ with

make docs

Contributing¶

Please report issues or discuss feature requests on Pymagicc’s issue tracker.

You can also contact the pymagicc authors via email: mailto:rob.g@web.de,zebedee.nicholls@climate-energy-college.org

Releasing¶

To release a new version of Pymagicc, there are a number of steps which need to be taken.

Firstly, ensure that all formatting is correct by running make black and make flake8. Make any changes which they require/recommend.

Next make sure all the tests are passing. You can run the tests with make test. Then make sure all the notebooks are passing their tests. The notebook tests can be run with make test-notebooks.

Having passed all the formatting and tests locally, you should then push the changes and ensure that all the code passes CI.

Next all the documentation should be checked and updated where necessary. This includes ensuring that the Changelog contains all major changes.

Then the next version number needs to be chosen. We follow Semantic versioning, this means that we have versions which are in the format “vMajor.Minor.Patch”. We then increment the:

‘Major’ when we make backwards-incompatible API changes
‘Minor’ when we add functionality in a backwards-compatible way
‘Patch’ when we make backwards-compatible bug fixes

Having performed all these steps, tag the new release with git tag vX.Y.Z. Push all the changes to GitHub with

git push origin master --tags

Then, a new version can be released on PyPI (see notes below about setting up PyPI and test releases) with (getting setup instructions can be found here)

make publish-on-pypi

To test the released version, one can run

make test-pypi-install

to install Pymagicc in a temporary directory and print its version number.

To ensure the latest Pymagicc version can run in the Mybinder notebook click the “Launch Binder” link in the Readme on GitHub. This build might take a while. The Binder notebook will install the latest version available on PyPI.

Finally, the new version needs to be turned into a release. This requires visiting https://github.com/openscm/pymagicc/releases, pressing ‘Draft a new release’, choosing the tag you just pushed, filling out the form and pressing ‘Publish release’. Having done these steps, the package will be automatically archived on Zenodo.

Setting up PyPI¶

To setup an account with PyPI that will work with our Makefile, follow the ‘Register for PyPI’ section of this guide. We repeat the key details here.

You must first register for PyPI and the test PyPI sites at https://pypi.org/account/register/ and https://test.pypi.org/account/register/ respectively. Then, in your home directory you need to create a file called .pypirc which has the following information.

[distutils]
index-servers=
    testpypi
    pypi

[testpypi]
repository = https://testpypi.python.org/pypi
username = name_of_the_user
password = hunter2  # optional, otherwise you have to type it everytime

[pypi]
repository = https://pypi.python.org/pypi
username = name_of_the_user
password = hunter2  # optional, otherwise you have to type it everytime

Test release¶

To test publishing on PyPI’s testing instance it is possible to use the publish-on-testpypi and test-testpypi-install tasks. Versions uploaded there should be deleted after testing.