Development notes

Repository organization

  • item/ — Python code for accessing & maintaining the database.

    • data/Meta -data about the iTEM databases. Actual data is stored separately; see below.

      • model/ — Metadata about the iTEM model database. Many of these files are in YAML format (Wikipedia), with more detailed comments in-line.

        • models.yaml — description of the iTEM participating models & teams.

        • dimensions/ — information about the data dimensions of the model database.

        • Other directories:

          • are named to match the keys in models.yaml,

          • contain model-specific metadata, including but not limited to:

            • regions.yaml: regional aggregation.

            • scenarios.yaml: descriptions of scenarios submitted to each iTEM workshop.

      • concepts.yaml, measures.yaml, spec.yaml — specifications of data to be submitted for for the 3rd iTEM MIP.

      • item_config_example.yaml — an example configuration file.

Code style

  • Run the following tools on all new and modified code:

    isort . && black . && mypy . && flake8

    The continuous integration workflow checks that these have been applied; PRs will fail unless they are.

  • Document all public classes and functions following the NumPy docstring format.

  • Ensure new items appear in the built documentation.

  • All code must be importable from within item.

  • Clear all cell output, execution counts, etc. from IPython notebooks committed to the repository.

Preparing a new release

Before releasing, check:

Address any failures before releasing.

  1. Edit doc/whatsnew.rst to replace “Next release” with the version number and date. Make a commit with a message like “Mark vX.Y.Z in whatsnew.rst”.

  2. Tag the version, e.g.:

    $ git tag v2030.10.4b4

    item uses a versioning scheme of [year].[month].[day]. For instance, the version released on October 4, 2030 will have the version 2030.10.4. Note that:

    • There are no leading zeroes.

    • If two versions are to be released in a single day—for instance, to fix a bug only spotted after release—a fourth version part can be added, e.g. 2030.10.4.1.

  3. Test-build and check the source and binary packages:

    $ rm -rf build dist
    $ python bdist_wheel sdist
    $ twine check dist/*

    Address any warnings or errors that appear. If needed, make a new commit and go back to step (2).

  4. Upload the packages to the TEST instance of PyPI:

    $ twine upload -r testpypi dist/*
  5. Check at that:

    • The package can be downloaded, installed and run.

    • The README is rendered correctly.

    • Links to the documentation go to the correct version.

    If not, modify the code and go back to step (2).

  6. Upload to PyPI:

    $ twine upload dist/*
  7. Push the commit(s) and tag to GitHub:

    $ git push --tags
  8. Edit doc/whatsnew.rst to add a new heading for the next release.