From 70f4e01104e0b778c552a2a0171f9fd5ba27a1db Mon Sep 17 00:00:00 2001 From: Manuel Barkhau Date: Wed, 5 Dec 2018 09:37:34 +0100 Subject: [PATCH] release preparation --- .gitlab-ci.yml | 2 +- CHANGELOG.md | 7 ++ README.md | 192 ++++++++++++++++++----------------- bootstrapit.sh | 3 + makefile.config.make | 2 +- requirements/development.txt | 11 ++ requirements/pypi.txt | 1 + setup.cfg | 18 ++-- setup.py | 16 ++- 9 files changed, 145 insertions(+), 107 deletions(-) diff --git a/.gitlab-ci.yml b/.gitlab-ci.yml index cc9269c..368402a 100644 --- a/.gitlab-ci.yml +++ b/.gitlab-ci.yml @@ -10,7 +10,7 @@ unit: - make lint - make mypy - make test - coverage: '/TOTAL.*?(\d+\%)/' + coverage: '/^(TOTAL|src).*?(\d+\%)$/' artifacts: paths: - htmlcov/ diff --git a/CHANGELOG.md b/CHANGELOG.md index c6b05e3..92b9a94 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -1,5 +1,12 @@ # Changelog for https://gitlab.com/mbarkhau/pycalver +## v201811.0008-beta + + - Add version tags using git/hg. + - Use git/hg tags as SSOT for most recent version. + - Start using https://gitlab.com/mbarkhau/bootstrapit + - Move to https://gitlab.com/mbarkhau/pycalver + ## v201809.0001-alpha - Initial release diff --git a/README.md b/README.md index 286be15..1447aee 100644 --- a/README.md +++ b/README.md @@ -1,33 +1,45 @@ -# PyCalVer: Automatic CalVer Versioning for Python Packages +# [PyCalVer: Automatic CalVer Versioning for Python Packages][repo_ref] -PyCalVer is a simple versioning system. It version strings -everywhere in your project, it generates git/mercurial tags and -is compatible with python packaging software +PyCalVer is a simple calendar based versioning system. With a single +`pycalver bump` command it will: + + - Automatically update version strings across files in your project. + - Commit those changes and tag the commit with the new version. + +Version strings generated by pycalver are compatible with python +packaging software [setuptools](https://setuptools.readthedocs.io/en/latest/setuptools.html#specifying-your-project-s-version>) [PEP440](https://www.python.org/dev/peps/pep-0440/). -[![Build Status][build_img]][build_ref] -[![Code Coverage][codecov_img]][codecov_ref] + +Project/Repo: + [![MIT License][license_img]][license_ref] -[![Code Style: sjfmt][style_img]][style_ref] -[![Type Checked with mypy][mypy_img]][mypy_ref] -[![PyCalVer v201809.0002-beta][version_img]][version_ref] -[![PyPI Version][pypi_img]][pypi_ref] -[![PyPI Downloads][downloads_img]][downloads_ref] -[![PyPI Wheel][wheel_img]][wheel_ref] [![Supported Python Versions][pyversions_img]][pyversions_ref] +[![PyCalVer v201809.0002-beta][version_img]][version_ref] +[![PyPI Releases][pypi_img]][pypi_ref] +[![PyPI Downloads][downloads_img]][downloads_ref] + +Code Quality/CI: + +[![Type Checked with mypy][mypy_img]][mypy_ref] +[![Code Style: sjfmt][style_img]][style_ref] +[![Code Coverage][codecov_img]][codecov_ref] +[![Build Status][build_img]][build_ref] -| Name | role | since | until | -|----------------------------|------------|---------|-------| -| Manuel Barkhau (@mbarkhau) | maintainer | 2018-09 | - | +| Name | role | since | until | +|----------------------------|-------------------|---------|-------| +| Manuel Barkhau (@mbarkhau) | author/maintainer | 2018-09 | - | + [](TOC) - [Introduction](#introduction) @@ -56,9 +68,20 @@ is compatible with python packaging software ## Introduction -The PyCalVer package provides the `pycalver` command and module -to generate version strings. These use the following format: -`v{calendar_version}.{build_number}[-{release_tag}]` +The PyCalVer package provides the `pycalver` command to generate +version strings. The version strings have three parts: + +``` + + o Year and Month of Build + | o Sequential Build Number + | | o Release Tag (optional) + | | | + ---+--- --+-- --+-- + v201812 .0123 -beta + + +``` Some examples: @@ -72,10 +95,7 @@ v202207.18133 v202207.18134 ``` -The `pycalver bump` command parses your files for such strings -and rewrites them with an incremented version string. - -### Format +### Version String Format The format for PyCalVer version strings can be parsed with this regular expression: @@ -131,7 +151,7 @@ assert version_info == { ### Versioning Behaviour -To illustrate how PyCalVer increments version strings, we can use +To see how version strings are incremented, we can use `pycalver incr`: ```shell @@ -148,15 +168,16 @@ This is the simple case: - The build number is incremented by 1. - The optional release tag is preserved as is. -Here is how to explicitly update the release tag: +You can explicitly update the release tag using the +`--release=` argument: ```shell -$ pycalver incr v201801.0033-beta --release=alpha -PyCalVer Version: v201809.0034-alpha -PEP440 Version: 201809.34a0 -$ pycalver incr v201801.0033-beta --release=final -PyCalVer Version: v201809.0034 -PEP440 Version: 201809.34 +$ pycalver incr v201801.0033-alpha --release=beta +PyCalVer Version: v201809.0034-beta +PEP440 Version: 201809.34b0 +$ pycalver incr v201809.0034-beta --release=final +PyCalVer Version: v201809.0035 +PEP440 Version: 201809.35 ``` The version number is padded with extra zeros, to maintain the @@ -175,10 +196,9 @@ lexical ids. ### Lexical Ids -The padded build number will occasionally have to be expanded. In -order to preserve both lexical ordering as well numerical -ordering, build numbers are incremented in a peculiar way. -Examples will perhaps illustrate more clearly. +The build number padding may eventually be exhausted. In order to +preserve both lexical ordering, build numbers are incremented in +a special way. Examples will perhaps illustrate more clearly. ```python "0001" @@ -197,7 +217,7 @@ Examples will perhaps illustrate more clearly. What is happening here is that the left-most digit is incremented early/preemptively. Whenever the left-most digit would change, -the width of the id is expanded using this simple formula: +the padding of the id is expanded using this simple formula: ```python prev_id = "0999" @@ -207,17 +227,40 @@ if prev_id[0] != next_id[0]: # "0" != "1" ``` This behaviour ensures that the following semantic is always -preserved: `old_version < new_version`. This will even be the -case if the version number was incremented twice in the same -month. +preserved: `old_version < new_version`. This will be the case, +even if the padding was expanded and the version number was +incremented multiple times in the same month. To illustrate the +issue, imagine we did not expand the padding and instead just +incremented numerically. + +```python +"0001" +"0002" +"0003" +... +"0999" +"1000" +... +"9999" +"10000" +``` + +Here we eventually run into a build number where the lexical +ordering is not preserved, since `"9999" < "10000" == False`. +This is a very rare corner case, but it's better to not have +to think about it. + +Just as an example of why lexical ordering is a nice property to +have, there are lots of software which read git tags, but which +have no logic to parse version strings, which can nonetheless +order the version tags correctly. ## Usage ### Configuration -The fastest way to setup a project is to invoke -`pycalver init`. +The fastest way to setup a project is to use `pycalver init`. ```shell @@ -227,24 +270,21 @@ Updated setup.cfg ``` This will add the something like the following to your -`setup.cfg`: +`setup.cfg` (depending on what files you have in your project): ```ini [pycalver] commit = True tag = True +push = True -[pycalver:file:setup.cfg] -patterns = +[pycalver:file_patterns] +setup.cfg = current_version = {version} - -[pycalver:file:setup.py] -patterns = +setup.py = "{version}", "{pep440_version}", - -[pycalver:file:README.md] -patterns = +README.md = {version} {pep440_version} ``` @@ -258,47 +298,16 @@ additional changes you might need to make. current_version = v201809.0001-beta commit = True tag = True +push = True -[pycalver:file:setup.cfg] -patterns = +[pycalver:file_patterns] +setup.cfg = current_version = {version} - -[pycalver:file:setup.py] -patterns = +setup.py = version="{pep440_version}" - -[pycalver:file:src/myproject.py] -patterns = +src/myproject.py = __version__ = "{version}" - -[pycalver:file:README.md] -patterns = - [PyCalVer {calver}{build}-{release}] - img.shields.io/badge/PyCalVer-{calver}{build}--{release}-blue -``` - -You can omit `patterns` if the default patterns are sufficient. -These are: - -```ini -patterns = - {version} - {pep440_version} -``` - -This allows for a shorter (albeit less explicit) configuration: - -```ini -[pycalver] -current_version = v201809.0001-beta -commit = True -tag = True - -[pycalver:file:setup.cfg] -[pycalver:file:setup.py] -[pycalver:file:src/myproject.py] -[pycalver:file:README.md] -patterns = +README.md = [PyCalVer {calver}{build}-{release}] img.shields.io/badge/PyCalVer-{calver}{build}--{release}-blue ``` @@ -656,6 +665,8 @@ because I don't think breaking changes should ever be +[repo_ref]: https://gitlab.com/mbarkhau/pycalver + [build_img]: https://gitlab.com/mbarkhau/pycalver/badges/master/pipeline.svg [build_ref]: https://gitlab.com/mbarkhau/pycalver/pipelines @@ -665,23 +676,20 @@ because I don't think breaking changes should ever be [license_img]: https://img.shields.io/badge/License-MIT-blue.svg [license_ref]: https://gitlab.com/mbarkhau/pycalver/blob/master/LICENSE -[mypy_img]: https://img.shields.io/badge/mypy-100%25-green.svg +[mypy_img]: https://img.shields.io/badge/mypy-checked-green.svg [mypy_ref]: http://mypy-lang.org/ [style_img]: https://img.shields.io/badge/code%20style-%20sjfmt-f71.svg [style_ref]: https://gitlab.com/mbarkhau/straitjacket/ -[pypi_img]: https://img.shields.io/pypi/v/pycalver.svg -[pypi_ref]: https://gitlab.com/mbarkhau/pycalver/blob/master/CHANGELOG.rst - [downloads_img]: https://pepy.tech/badge/pycalver [downloads_ref]: https://pepy.tech/project/pycalver [version_img]: https://img.shields.io/badge/PyCalVer-v201809.0002--beta-blue.svg [version_ref]: https://pypi.org/project/pycalver/ -[wheel_img]: https://img.shields.io/pypi/wheel/pycalver.svg -[wheel_ref]: https://pypi.org/project/pycalver/#files +[pypi_img]: https://img.shields.io/badge/PyPI-wheels-green.svg +[pypi_ref]: https://pypi.org/project/pycalver/#files [pyversions_img]: https://img.shields.io/pypi/pyversions/pycalver.svg [pyversions_ref]: https://pypi.python.org/pypi/pycalver diff --git a/bootstrapit.sh b/bootstrapit.sh index e166707..1dd1ee2 100644 --- a/bootstrapit.sh +++ b/bootstrapit.sh @@ -13,7 +13,10 @@ PACKAGE_NAME="pycalver" GIT_REPO_NAMESPACE="mbarkhau" GIT_REPO_DOMAIN="gitlab.com" +PACKAGE_VERSION="v201912.0001-beta" + DEFAULT_PYTHON_VERSION="python=3.6" +SUPPORTED_PYTHON_VERSIONS="python=2.7 pypy2.7 pypy3.4 python=3.5 python=3.6 python=3.7" IS_PUBLIC=1 diff --git a/makefile.config.make b/makefile.config.make index 3facdc3..6d6578a 100644 --- a/makefile.config.make +++ b/makefile.config.make @@ -18,4 +18,4 @@ DEVELOPMENT_PYTHON_VERSION := python=3.6 # - python=3.7 # - pypy2.7 # - pypy3.5 -SUPPORTED_PYTHON_VERSIONS := python=3.6 +SUPPORTED_PYTHON_VERSIONS := python=2.7 python=3.4 python=3.6 diff --git a/requirements/development.txt b/requirements/development.txt index bd94e7d..ab63a13 100644 --- a/requirements/development.txt +++ b/requirements/development.txt @@ -10,6 +10,16 @@ # https://documen.tician.de/pudb/ pudb +# Quick-and-dirty debugging output for tired programmers +# https://pypi.org/project/q/ +q + +# backtrace manipulates Python tracebacks to make them more +# readable. It provides different configuration options for +# coloring and formatting. +# https://github.com/nir0s/backtrace +backtrace + # Py-Spy: A sampling profiler for Python programs. # https://github.com/benfred/py-spy # This is good for coarse grained profiling (even on production) @@ -24,3 +34,4 @@ snakeviz # add one after you've tested it and found it to be actually useful. ipython # nuff said + diff --git a/requirements/pypi.txt b/requirements/pypi.txt index bc7d91a..56bf91f 100644 --- a/requirements/pypi.txt +++ b/requirements/pypi.txt @@ -10,3 +10,4 @@ pathlib2 typing click +toml diff --git a/setup.cfg b/setup.cfg index 329b2a5..5ba6fd9 100644 --- a/setup.cfg +++ b/setup.cfg @@ -67,20 +67,16 @@ addopts = --doctest-modules current_version = v201811.0007-beta commit = True tag = True +push = True -[pycalver:file:setup.cfg] -patterns = + +[pycalver:file_patterns] +"setup.cfg" = current_version = {version} - -[pycalver:file:setup.py] -patterns = +"setup.py" = version="{pep440_version}" - -[pycalver:file:src/pycalver/__init__.py] -patterns = +"src/pycalver/__init__.py" = __version__ = "{version}" - -[pycalver:file:README.md] -patterns = +"README.md" = [PyCalVer {calver}{build}-{release}] img.shields.io/badge/PyCalVer-{calver}{build}--{release}-blue diff --git a/setup.py b/setup.py index d2bffd9..8f2bd36 100644 --- a/setup.py +++ b/setup.py @@ -5,6 +5,7 @@ # SPDX-License-Identifier: MIT import os +import sys import setuptools @@ -25,7 +26,15 @@ install_requires = [ ] -long_description = "\n\n".join((read("README.md"), read("CONTRIBUTING.md"), read("CHANGELOG.md"))) +package_dir = {"": "src"} + + +if any(arg.startswith("bdist") for arg in sys.argv): + import lib3to6 + package_dir = lib3to6.fix(package_dir) + + +long_description = "\n\n".join((read("README.md"), read("CHANGELOG.md"))) setuptools.setup( @@ -41,7 +50,7 @@ setuptools.setup( long_description=long_description, long_description_content_type="text/markdown", packages=["pycalver"], - package_dir={"": "src"}, + package_dir=package_dir, install_requires=install_requires, entry_points=""" [console_scripts] @@ -60,6 +69,9 @@ setuptools.setup( "Operating System :: Microsoft :: Windows", "Operating System :: MacOS :: MacOS X", "Programming Language :: Python", + "Programming Language :: Python :: 2.7", + "Programming Language :: Python :: 3.4", + "Programming Language :: Python :: 3.5", "Programming Language :: Python :: 3.6", "Programming Language :: Python :: 3.7", "Programming Language :: Python :: Implementation :: CPython",