Information for developers

Submission of small bug fixes and features is encouraged. For larger features, please contact the author to discuss feasibility and structure.

Code style

Follow PEP 8 where possible.

Documentation style

Use NumPy docstring format. Language and grammar should follow Google style.

Development environment

A Visual Studio Code configuration file is provided in the project root when checked out via git, which sets some code format settings which should be followed. This configuration file is used automatically if the project is opened in Visual Studio Code from its root directory.

It may be useful to run Zero within a conda or pipenv environment to allow for separation of dependencies from your system and from other projects. In both cases it is still recommended to install Zero via pip. For rapid development, it is highly recommended to make the project editable so changes to project files reflect immediately in the library and CLI, and to install the extra dev dependencies to allow you to build the documentation and run code linting tools:

pip install -e .[dev]

Merge requests

If you have code to submit for inclusion in Zero, please open a merge request on GitLab targeting the develop branch. To keep the git repository’s merge graph clean, ideally you should make your changes on a branch with one of the following conventions depending on what kind of change you make:

  • feature/my-feature for new features

  • hotfix/my-fix for bug fixes

Replace my-feature or my-fix with an appropriate short description. This naming scheme roughly follows that presented in A successful Git branching model.

Creating new releases

The steps below should be followed when creating a new release:

  1. Ensure all tests pass and all bundled examples work as intended, and all documentation is up-to-date.

  2. Create a new release branch from develop, where x.x.x is the intended new version number: git checkout -b release/x.x.x develop.

  3. Update default user config and component library distributed_with keys to match the new intended version number.

  4. Commit changes and checkout develop.

  5. Checkout develop branch then merge release without fast-forwarding: git merge --no-ff release/x.x.x.

  6. Checkout master branch then merge release/x.x.x without fast-forwarding: git merge --no-ff release/x.x.x.

  7. Tag the release on master with the version: git tag -a x.x.x.

  8. Delete the release branch: git branch -d release/x.x.x.

  9. Push all changes to master and develop and the new tag to origin.

Note that when a new tag is pushed to the ligo.org GitLab server, the CI runner automatically creates and uploads a new PyPI release.

Updating PyPI (pip) package

This requires twine and the credentials for the Zero PyPI project.

By default, the GitLab CI runner will deploy a PyPI package automatically whenever a new tag is created. The instructions below are for when this must be done manually:

  1. Go to the source root directory.

  2. Checkout the master branch (so the release uses the correct tag).

  3. Remove previously generated distribution files: rm -rf build dist

  4. Create new distribution files: python setup.py sdist bdist_wheel

  5. (Optional) Upload distribution files to PyPI test server, entering the required credentials when prompted: python -m twine upload --repository-url https://test.pypi.org/legacy/ dist/*

    You can then check the package is uploaded properly by viewing the Zero project on the PyPI test server. You can also check that it installs correctly with: pip install --index-url https://test.pypi.org/simple/ --no-deps zero

    Note: even if everything installs correctly, the test package will not work correctly due to lack of dependencies (forced by the --no-deps flag, since they are not all available on the PyPI test server).

  6. Upload distribution files to PyPI, entering the required credentials when prompted: python -m twine upload dist/*

  7. Verify everything is up-to-date on PyPI.

API documentation