First create something that works (to provide business value).
Then something that’s beautiful (to lower maintenance costs).
Finally works on performance (to avoid wasting time on premature optimizations).
This project follows Semantic Versioning.
Which boils down to the following rules of thumb regarding stability:
Patch releases (
0.x.(n+1)upgrades) are bug-fix only. These releases must not break anything and keep backward-compatibility with
Minor releases (
0.(n+1).0upgrades) 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+1).0.0upgrades) make no promises about backwards-compability. Any API change requires a new major release.
Setup a development environment¶
This step is required for all the other sections from this page.
Check out latest development branch:
$ git clone email@example.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!
Install test dependencies and run unit-tests:
$ poetry run pytest
Run black to auto-format Python code:
$ poetry run black .
Then run Pylint code style checks:
$ poetry run pylint meta_package_manager
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
To update the auto-generated API documention:
$ poetry run sphinx-apidoc -f -o ./docs .
Once in a while, the maintainers of the project will refresh screenshots found
in the documentation and the
readme.rst file at the root of project.
To produce clean and fancy terminals screenshots, use either:
From time to time, especially before a release, the maintainers will review and rewrite the changelog to make it clean and readable. The idea is to have it stay 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:
This direct link should be available at the top of the changelog .
Check you are starting from a clean
$ 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 ./changelog.rst
Create a release commit, tag it and merge it back to
$ git add ./meta_package_manager/__init__.py ./changelog.rst $ git commit -m "Release vX.Y.Z" $ git tag "vX.Y.Z" $ git push $ git push --tags $ git checkout main $ 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¶
$ 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
$ git checkout develop $ poetry run bumpversion --verbose patch $ git add ./meta_package_manager/__init__.py ./changelog.rst $ git commit -m "Post release version bump." $ git push
Versions are automatically 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
$ poetry run bumpversion --verbose minor $ git add ./meta_package_manager/__init__.py ./changelog.rst $ git commit -m "Next release no longer bug-fix only. Bump revision." $ git push