Skip to content

Latest commit

 

History

History
107 lines (78 loc) · 6.01 KB

MAINTENANCE.md

File metadata and controls

107 lines (78 loc) · 6.01 KB
Raw

Maintenace

Maintenance is based on extra tools that are defined as optional dependencies in setup.py. The sections below refer to them as "extra requirements".

To automate maintenance as much as possible, this repository features three Github Actions:

  1. Test on push or pull request - see Testing
  2. Bump version - see Deployment
  3. Deploy to PyPI - see Deployment

Testing

You can find a series of unit tests in the tests directory. The recommended way to execute them is by using the nose module. It is installed as part of the test extra requirements.

To run the tests locally, execute python -m nose -v --exe within the project's root directory.

All tests are run automatically on new pull requests via the "Test on push or pull request" Github Action. This action triggers on:

  • new pull requests
  • pull request updates
  • commits being pushed to the master branch
  • manual dispatch via Github UI

Deployment

Deployment works by bumping the version, building a source distribution (sdist), and uploading it to PyPI using twine.

These steps are automated as part of the "Bump version" and "Deploy to PyPI" Github Actions. See below for details.

Versioning

This project follows the Semantic Versioning Specification.

To avoid human error, it is recommended to use the bump2version tool (configured in .bumpversion.cfg). bump2version can be installed locally using the deploy extra requirements. To manually bump the version, run bump2version <part>, where <part> is either major, minor, or patch.

Note 1: It is not recommended to run this tool manually. Instead, this step has been automated as part of the "Bump version" Github Action. To push the version-bumped commit back to the repo, the action requires more permissions than the default GITHUB_TOKEN provides. Instead, it requires a personal access token (PAT; stored and accessed as the PERSONAL_ACCESS_TOKEN secret). This allows writing to the repository and triggering the "Deploy to PyPI" Github Action.

Note 2: Due to security restrictions, pull requests from forked repositories do not have access to the workflow's secret. As a result, the "Bump version" workflow will fail and not trigger a deployment. In these cases, the deployment needs to be triggered by manually dispatching the workflow or pushing a tagged commit.

Building a distribution

The lowest common denominator for distributing a Python package is a source distribution. It is a single artifact that can be installed and tested on Python 2 and Python 3.

Note: It is best practice to also provide pure Python wheels. But the project would have to provide different wheels for Python 2 and 3 which would double the testing effort. Until project support for Python 2.7 is dropped (see #152 for reference), it is likely the best option to only distribute source distributions.

The "Test on push or pull request" Github Action is setup to install and test the same source distribution that is also distributed to PyPI.

Python Package Index (PyPI)

The Python Package Index (PyPI) is the official repository of software for the Python programming language. Its tight integration with the recommended package installer (pip) is the easiest way for users to install the project. It also allows other projects to easily define this project as a dependency.

When triggered, the "Deploy to PyPI" Github Action builds a source distribution, and deploys it to PyPI. See Github Action usage below for information when the Github Action is triggered and how to control the version part that will be bumped.

Authentification

It is strongly recommended to use PyPI API tokens for the deployment authentification. The "Deploy to PyPI" Github Action is set up to use the PYPI_TOKEN repository secret as an API token.

Github Action usage

The Bump version Github Action triggers on:

The "Deploy to PyPI" Github Action triggers on:

  • tags being pushed to the repository, including version bumps created by the Bump version Github Action

There are four version part values for automatic version bumping: none, major, minor, patch (default). For pull requests, you can assign one of the bump:* labels. If no label is assigned, the action will default to bumping the patch part. Should more than one bump:* label be assigned, the Github action will bump the part with the highest priority (none > major > minor > patch).

For the manual action dispatch, one can pass one of the values directly to the action via the UI.