Development

Philosophy

  1. First create something that work (to provide business value).

  2. Then something that’s beautiful (to lower maintenance costs).

  3. Finally works on performance (to avoid wasting time on premature optimizations).

Stability policy

This project follows Semantic Versioning.

Which boils down to the following rules of thumb regarding stability:

  • Patch releases (0.x.n0.x.(n+1) upgrades) are bug-fix only. These releases must not break anything and keeps backward-compatibility with 0.x.* and 0.(x-1).* series.

  • Minor releases (0.n.*0.(n+1).0 upgrades) includes any non-bugfix changes. These releases must be backward-compatible with any 0.n.* version but are allowed to drop compatibility with the 0.(n-1).* series and below.

  • Major releases (n.*.*(n+1).0.0 upgrades) are not planned yet, unless we introduce huge changes to the project.

Build status

Branch

master

develop

Unittests

Unittests status

Unittests status

Coverage

Coverage Status

Coverage Status

Quality

Code Quality

Code Quality

Dependencies

Requirements freshness

Requirements freshness

Documentation

Documentation Status

Documentation Status

Setup a development environment

This step is required for all the other sections from this page.

Check out latest development branch:

$ git clone git@github.com:kdeldycke/meta-package-manager.git
$ cd ./meta-package-manager
$ git checkout develop

Install package in editable mode with all development dependencies:

$ pip install poetry
$ poetry install

Now you’re ready to hack and abuse git!

Unit-tests

Install test dependencies and run unit-tests:

$ poetry run pytest

Coding style

Run black to auto-format Python code:

$ poetry run black .

Then run pycodestyle and Pylint code style checks:

$ poetry run pycodestyle
$ poetry run pylint meta_package_manager

Documentation

The documentation you’re currently reading can be built locally with Sphinx:

$ poetry install --extras docs
$ poetry run sphinx-build -b html ./docs ./docs/html

And once in a while, it’s good to upgrade the graph of package dependencies:

$ poetry show --all --no-dev --tree

Labels

GitHub labels for issues and pull requests are automatticaly generated and synchronized by a GitHub action workflow.

Screenshots

Once in a while, refresh screenshots found in the docs and the README file at the root of project.

To produce clean and fancy terminals screenshots, use either:

Changelog

From time to time, especially before a release, review and rewrite the changelog to make it clean and readeable. The idea is to have it stays in the spirit of the keep a changelog manifesto.

Most (if not all) changes can be derived by simply comparing the last tagged release with the develop branch: https://github.com/kdeldycke/meta-package-manager/compare/vX.X.X...develop. This direct link should be available at the top of the changelog .

Release process

Check your starting from a clean develop branch:

$ git checkout develop

Revision should already be set to the next version, so we just need to set the released date in the changelog:

$ vi ./CHANGES.rst

Create a release commit, tag it and merge it back to master branch:

$ git add ./meta_package_manager/__init__.py ./CHANGES.rst
$ git commit -m "Release vX.Y.Z"
$ git tag "vX.Y.Z"
$ git push
$ git push --tags
$ git checkout master
$ git pull
$ git merge "vX.Y.Z"
$ git push

The next phases of the release process are automated and should be picked up by GitHub actions. If not, the next section details the manual deployment process.

Manual build and deployment

Build packages:

$ poetry build

For a smooth release, you also need to validate the rendering of package’s long description on PyPi, as well as metadata:

$ poetry check
$ poetry run twine check ./dist/*

Publish packaging to PyPi:

$ poetry publish

Update revision with bump2version and set it back to development state by increasing the patch level.

$ git checkout develop
$ poetry run bumpversion --verbose patch
$ git add ./meta_package_manager/__init__.py ./CHANGES.rst
$ git commit -m "Post release version bump."
$ git push

Version bump

Versions are automatticaly bumped to their next patch revision at release (see above). In the middle of your development, if the upcoming release is no longer bug-fix only, or gets really important, feel free to bump to the next minor or major:

$ poetry run bumpversion --verbose minor
$ git add ./meta_package_manager/__init__.py ./CHANGES.rst
$ git commit -m "Next release no longer bug-fix only. Bump revision."
$ git push