Contributing

Koordinates welcomes bug reports and contributions by the community to this module. This process is intended to be as easy as possible for both contributors and the Koordinates development team.

Testing

The client includes a suite of unit and functional tests. These should be used to verify that your changes don’t break existing functionality, and that compatibility is maintained across supported Python versions. Tests run automatically on Buildkite for branch commits and pull requests.

To run the tests you need to:

$ pip install -r requirements-test.txt
$ tox

Patches

All patches should be sent as a pull request on GitHub, including tests and documentation where needed. If you’re fixing a bug or making a large change the patch must include test coverage before it will be merged.

If you’re uncertain about how to write tests, take a look at some existing tests that are similar to the code you’re changing.

Release Process

This guide describes the process to release a new version of the library. In this example, v0.0.0. The library follows the Semantic Versioning guidelines, so select major, minor, and patch version numbers appropriately.

Preparations

1. Close or update all tickets for the next milestone on Github..

2. Update the minimum required versions of dependencies in pyproject.toml. Update the exact version of all entries in requirements.txt.

3. Run tox from the project root. All tests for all supported Python versions must pass:

   $ tox
   [...]
   ________ summary ________
   py37: commands succeeded
   ...
   congratulations :)
   

   Note

   Tox will use the requirements-test.txt to setup the virtualenvs, so make sure you’ve updated it.

4. Build the Sphinx docs. Make sure there are no errors and undefined references.

   $ make clean docs
   

   Note

   You will need to install dev dependencies in requirements-dev.txt to build documentation.

5. Check the Buildkite build is passing.

6. Update the version number in koordinates/__init__.py and commit:

   $ git commit -m 'Version 0.0.0 release' koordinates/__init__.py
   

   Warning

   Don’t tag and push the changes yet so that you can safely rollback if you need change something!

7. Create a draft release in Github with a list of changes, acknowledgements, etc.

Build and release

1. Test the release process. Build a source distribution and test it:

   $ python3 -m build
   $ ls dist/
   koordinates-0.7.0-py3-none-any.whl  koordinates-0.7.0.tar.gz
   

   Try installing them:

   $ rm -rf /tmp/koordinates-sdist  # ensure clean state
   $ virtualenv /tmp/koordinates-sdist
   $ source /tmp/koordinates-sdist/bin/activate
   $ /tmp/koordinates-sdist/bin/pip install dist/koordinates-0.7.0.tar.gz
   $ /tmp/koordinates-sdist/bin/python
   >>> import koordinates
   

2. Create or check your accounts for the test server <https://testpypi.python.org/pypi> and PyPI. Update your ~/.pypirc with your credentials:

   [distutils]
   index-servers =
       pypi
       test
   
   [test]
   repository = https://test.pypi.org/legacy/
   username = __apitoken__
   password = <apikey>
   
   [pypi]
   username = __apitoken__
   password = <apikey>
   

3. Upload the distributions for the new version to the test server and test the installation again:

   $ twine upload -r test dist/*
   
   $ rm -rf /tmp/koordinates-sdist  # ensure clean state
   $ virtualenv /tmp/koordinates-sdist
   $ source /tmp/koordinates-sdist/bin/activate
   $ /tmp/koordinates-sdist/bin/pip install -i https://testpypi.python.org/pypi --extra-index-url https://pypi.python.org/pypi koordinates
   

4. Check if the package is displayed correctly: https://testpypi.python.org/pypi/koordinates

5. Upload the package to PyPI and test its installation one last time:

   $ twine upload -r pypi dist/*
   
   $ rm -rf /tmp/koordinates-sdist  # ensure clean state
   $ virtualenv /tmp/koordinates-sdist
   $ source /tmp/koordinates-sdist/bin/activate
   $ pip install -U koordinates
   

6. Check the package is displayed correctly: https://pypi.python.org/pypi/koordinates

Post release

1. Push your changes:

   $ git tag -a v0.0.0 -m "Version 0.0.0"
   $ git push origin v0.0.0
   

2. Activate the documentation build for the new version.

3. Make the Github release public.

4. Update related Help pages if necessary.