release preparation

.gitlab-ci.yml

@@ -10,7 +10,7 @@ unit:
     - make lint
     - make mypy
     - make test
-  coverage: '/TOTAL.*?(\d+\%)/'
+  coverage: '/^(TOTAL|src).*?(\d+\%)$/'
   artifacts:
     paths:
       - htmlcov/

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

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
+PyCalVer is a simple calendar based versioning system. With a single
-everywhere in your project, it generates git/mercurial tags and
+`pycalver bump` command it will:
-is compatible with python packaging software
+
+ - 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 |
+|            Name            |        role       |  since  | until |
-|----------------------------|------------|---------|-------|
+|----------------------------|-------------------|---------|-------|
-| Manuel Barkhau (@mbarkhau) | maintainer | 2018-09 | -     |
+| Manuel Barkhau (@mbarkhau) | author/maintainer | 2018-09 | -     |
 
 
 <!--
+  To update the TOC:
   $ pip install md-toc
   $ md_toc -i gitlab README.md
 -->
 
+
 [](TOC)
 
   - [Introduction](#introduction)
@@ -56,9 +68,20 @@ is compatible with python packaging software
 
 ## Introduction
 
-The PyCalVer package provides the `pycalver` command and module
+The PyCalVer package provides the `pycalver` command to generate
-to generate version strings. These use the following format:
+version strings. The version strings have three parts:
-`v{calendar_version}.{build_number}[-{release_tag}]`
+
+```
+
+    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
+### Version String Format
-and rewrites them with an incremented 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=<tag>` argument:
 
 ```shell
-$ pycalver incr v201801.0033-beta --release=alpha
+$ pycalver incr v201801.0033-alpha --release=beta
-PyCalVer Version: v201809.0034-alpha
+PyCalVer Version: v201809.0034-beta
-PEP440 Version: 201809.34a0
+PEP440 Version: 201809.34b0
-$ pycalver incr v201801.0033-beta --release=final
+$ pycalver incr v201809.0034-beta --release=final
-PyCalVer Version: v201809.0034
+PyCalVer Version: v201809.0035
-PEP440 Version: 201809.34
+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
+The build number padding may eventually be exhausted. In order to
-order to preserve both lexical ordering as well numerical
+preserve both lexical ordering, build numbers are incremented in
-ordering, build numbers are incremented in a peculiar way.
+a special way. Examples will perhaps illustrate more clearly.
-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
+preserved: `old_version < new_version`. This will be the case,
-case if the version number was incremented twice in the same
+even if the padding was expanded and the version number was
-month.
+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
+The fastest way to setup a project is to use `pycalver init`.
-`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]
+[pycalver:file_patterns]
-patterns =
+setup.cfg =
     current_version = {version}
-
+setup.py =
-[pycalver:file:setup.py]
-patterns =
     "{version}",
     "{pep440_version}",
-
+README.md =
-[pycalver:file:README.md]
-patterns =
     {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]
+[pycalver:file_patterns]
-patterns =
+setup.cfg =
     current_version = {version}
-
+setup.py =
-[pycalver:file:setup.py]
-patterns =
     version="{pep440_version}"
-
+src/myproject.py =
-[pycalver:file:src/myproject.py]
-patterns =
     __version__ = "{version}"
-
+README.md =
-[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 =
     [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
+[pypi_img]: https://img.shields.io/badge/PyPI-wheels-green.svg
-[wheel_ref]: https://pypi.org/project/pycalver/#files
+[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

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
 

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

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
+

requirements/pypi.txt

@@ -10,3 +10,4 @@
 pathlib2
 typing
 click
+toml

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}
-
+"setup.py" =
-[pycalver:file:setup.py]
-patterns =
     version="{pep440_version}"
-
+"src/pycalver/__init__.py" =
-[pycalver:file:src/pycalver/__init__.py]
-patterns =
     __version__ = "{version}"
-
+"README.md" =
-[pycalver:file:README.md]
-patterns =
     [PyCalVer {calver}{build}-{release}]
     img.shields.io/badge/PyCalVer-{calver}{build}--{release}-blue

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",