technofab/bumpver
1
0
Fork 0
mirror of https://github.com/TECHNOFAB11/bumpver.git synced 2025-12-12 06:20:08 +01:00
Code Issues Projects Releases Packages Wiki Activity Actions

Update readme

Browse source
This commit is contained in:
Manuel Barkhau 2018-11-05 00:18:49 +01:00
parent d951483a83
commit 3af39f2183
5 changed files with 346 additions and 342 deletions
Download patch file Download diff file Expand all files Collapse all files

7
CHANGELOG.rst
View file

@ -1,7 +0,0 @@
Changelog for pycalver
======================
v201809.0001-alpha
------------------
- Initial release

322
README.md
View file

@ -1,65 +1,66 @@
PyCalVer: Automatic CalVer Versioning for Python Packages
=========================================================
# PyCalVer: Automatic CalVer Versioning for Python Packages
PyCalVer is a very simple versioning system,
which is 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/>`_
).
PyCalVer is a very simple versioning system, which is 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/).
.. start-badges
.. list-table::
:stub-columns: 1
* - package
- | |license| |wheel| |pyversions| |pypi| |version|
* - tests
- | |travis| |mypy| |coverage|
.. |travis| image:: https://api.travis-ci.org/mbarkhau/pycalver.svg?branch=master
:target: https://travis-ci.org/mbarkhau/pycalver
:alt: Build Status
.. |mypy| image:: http://www.mypy-lang.org/static/mypy_badge.svg
:target: http://mypy-lang.org/
:alt: Checked with mypy
.. |coverage| image:: https://codecov.io/gh/mbarkhau/pycalver/branch/master/graph/badge.svg
:target: https://codecov.io/gh/mbarkhau/pycalver
:alt: Code Coverage
.. |license| image:: https://img.shields.io/pypi/l/pycalver.svg
:target: https://github.com/mbarkhau/pycalver/blob/master/LICENSE
:alt: MIT License
.. |pypi| image:: https://img.shields.io/pypi/v/pycalver.svg
:target: https://github.com/mbarkhau/pycalver/blob/master/CHANGELOG.rst
:alt: PyPI Version
.. |version| image:: https://img.shields.io/badge/CalVer-v201809.0002--beta-blue.svg
:target: https://calver.org/
:alt: CalVer v201809.0002-beta
.. |wheel| image:: https://img.shields.io/pypi/wheel/pycalver.svg
:target: https://pypi.org/project/pycalver/#files
:alt: PyPI Wheel
.. |pyversions| image:: https://img.shields.io/pypi/pyversions/pycalver.svg
:target: https://pypi.python.org/pypi/pycalver
:alt: Supported Python Versions
[![Build Status][ci_build_img]][ci_build_ref]
[![Code Coverage][codecov_img]][codecov_ref]
[![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]
The PyCalVer package provides the ``pycalver`` command and
| Name | role | since | until |
|----------------------------|------------|---------|-------|
| Manuel Barkhau (@mbarkhau) | maintainer | 2018-09 | - |
<!--
$ pip install md-toc
$ md_toc -i gitlab README.md
-->
[](TOC)
- [PyCalVer: Automatic CalVer Versioning for Python Packages](#pycalver-automatic-calver-versioning-for-python-packages)
- [Introduction](#introduction)
- [https://regex101.com/r/fnj60p/10](#https-regex101-com-r-fnj60p-10)
- [Usage](#usage)
- [Installation](#installation)
- [Configuration](#configuration)
- [Pattern Search and Replacement](#pattern-search-and-replacement)
- [Other Versioning Software](#other-versioning-software)
- [Rational](#rational)
- [Some Details](#some-details)
- [Lexical Ids](#lexical-ids)
- [Realities of Verion Numbers](#realities-of-verion-numbers)
- [Should I use PyCalVer for my Project?](#should-i-use-pycalver-for-my-project)
- [Marketing/Vanity](#marketing-vanity)
- [Rational](#rational-1)
- [Breaking Things is a Big Deal](#breaking-things-is-a-big-deal)
- [A Word on Marketing](#a-word-on-marketing)
- [Commitment to Compatability](#commitment-to-compatability)
- [The Life of a Library](#the-life-of-a-library)
- [FAQ](#faq)
[](TOC)
## Introduction
The PyCalVer package provides the `pycalver` command and
module to generate version strings which follow the following
format: ``v{calendar_version}.{build_number}[-{release_tag}]``
format: `v{calendar_version}.{build_number}[-{release_tag}]`
Some examples:
.. code-block:
```
v201711.0001-alpha
v201712.0027-beta
v201801.0031
@ -67,18 +68,16 @@ Some examples:
...
v202207.18133
v202207.18134
```
The ``pycalver bump`` command will parse the files you configure
in ``setup.cfg`` for such strings and rewrite them with an
The `pycalver bump` command will parse the files you configure
in `setup.cfg` for such strings and rewrite them with an
updated version string.
The format accepted by PyCalVer can be parsed with this regular
expression:
.. code-block:: python
```python
import re
# https://regex101.com/r/fnj60p/10
@ -124,17 +123,16 @@ expression:
"build" : ".0033",
"release" : None,
}
```
## Usage
Installation
------------
### Installation
Before we look at project setup, we can simply install and test
by passing a version string to ``pycalver incr``.
.. code-block:: bash
by passing a version string to `pycalver incr`.
```shell
$ pip install pycalver
$ pycalver incr v201801.0033-beta
@ -148,31 +146,29 @@ by passing a version string to ``pycalver incr``.
$ pycalver incr v201809.1999
PyCalVer Version: v201809.22000
PEP440 Version: 201809.22000
```
The CalVer component is set to the current year and month, the
build number is incremented by one and the optional release tag
is preserved as is, unless specified otherwise via the
``--release=<tag>`` parameter.
`--release=<tag>` parameter.
Configuration
-------------
### Configuration
The fastest way to setup a project is to invoke
``pycalver init``.
`pycalver init`.
.. code-block:: bash
```shell
$ cd my-project
~/my-project$ pycalver init
Updated setup.cfg
```
This will add the following to your `setup.cfg`:
.. code-block:: ini
# setup.cfg
```ini
[bdist_wheel]
universal = 1
@ -190,20 +186,19 @@ The fastest way to setup a project is to invoke
"{version}",
"{pep440_version}",
[pycalver:file:README.rst]
[pycalver:file:README.md]
patterns =
{version}
{pep440_version}
```
Depending on your project, the above will probably cover all
version numbers across your repository. Something like the
following may illustrate additional changes you'll need to make.
following may illustrate additional changes you might need to
make.
.. code-block:: ini
# setup.cfg
```ini
[pycalver]
current_version = v201809.0001-beta
commit = True
@ -221,30 +216,28 @@ following may illustrate additional changes you'll need to make.
patterns =
__version__ = "{version}"
[pycalver:file:README.rst]
[pycalver:file:README.md]
patterns =
badge/CalVer-{calver}{build}-{release}-blue.svg
:alt: CalVer {version}
[PyCalVer {calver}{build}-{release}]
img.shields.io/badge/PyCalVer-{calver}{build}--{release}-blue
```
If ``patterns`` is not specified for a ``pycalver:file:``
If `patterns` is not specified for a `pycalver:file:`
section, the default patterns are used:
.. code-block:: ini
```ini
[pycalver:file:src/myproject.py]
patterns =
{version}
{pep440_version}
```
This allows us to less explicit but shorter configuration, like
This allows for a less explicit but shorter configuration, like
this:
.. code-block:: ini
```ini
[pycalver]
current_version = v201809.0001-beta
commit = True
@ -253,33 +246,30 @@ this:
[pycalver:file:setup.cfg]
[pycalver:file:setup.py]
[pycalver:file:src/myproject.py]
[pycalver:file:README.rst]
[pycalver:file:README.md]
patterns =
badge/CalVer-{calver}{build}-{release}-blue.svg
:alt: CalVer {version}
[PyCalVer {calver}{build}-{release}]
img.shields.io/badge/PyCalVer-{calver}{build}--{release}-blue
```
### Pattern Search and Replacement
Pattern Search and Replacement
------------------------------
``patterns`` is used both to search for version strings and to
`patterns` is used both to search for version strings and to
generate the replacement strings. The following placeholders are
available for use, everything else in a pattern is treated as
literal text.
.. table:: Patterns Placeholders
================== ======================
placeholder example
================== ======================
``pep440_version`` 201809.1b0
``version`` v201809.0001-alpha
``calver`` v201809
``year`` 2018
``month`` 09
``build`` .0001
``release`` -alpha
================== ======================
| placeholder | example |
|------------------|--------------------|
| `pep440_version` | 201809.1b0 |
| `version` | v201809.0001-alpha |
| `calver` | v201809 |
| `year` | 2018 |
| `month` | 09 |
| `build` | .0001 |
| `release` | -alpha |
Note that the separator/prefix characters are part of what is
matched and generated for a given placeholder, and they should
@ -288,26 +278,22 @@ not be included in your patterns.
A further restriction is, that a version string cannot span
multiple lines in your source file.
Now we can call ``pycalver bump`` to bump all occurrences of
Now we can call `pycalver bump` to bump all occurrences of
version strings in these files. Normally this will change local
files, but the ``--dry`` flag will instead display a diff of the
files, but the `--dry` flag will instead display a diff of the
changes that would be applied.
.. code-block:: bash
```shell
$ pycalver show
Current Version: v201809.0001-beta
PEP440 Version: 201809.1b0
$ pycalver bump --dry
TODO
Don't forget to git push --tags
Dont forget to do $ git push --tags
```
Other Versioning Software
-------------------------
### Other Versioning Software
This project is very similar to bumpversion, upon which it is
partially based, but since the PyCalVer version strings can be
@ -317,25 +303,25 @@ Most of the interaction that users will have is reduced to two
commands:
.. code-block:: bash
```shell
$ pycalver bump
TODO: Output
```
More rarely, when changing the release type:
.. code-block:: bash
```shell
$ pycalver bump --release beta
TODO: Output
$ pycalver bump --release final
TODO: Output
```
## Rational
Some Details
------------
### Some Details
- Version numbers are for public releases. For the purposes of
development of the project itself, reference VCS branches and
@ -352,11 +338,11 @@ regular expression:
These are the full version strings, for public announcements and
conversations it will often be sufficient to refer simply to
``v201801``, by which the most recent ``post`` release build of
`v201801`, by which the most recent `post` release build of
that month is meant.
```
version_str = "v201712.0027-beta"
version_dict = pycalver_re.match("v201712.0027-beta").groupdict()
import pkg_resources # from setuptools
@ -367,10 +353,10 @@ that month is meant.
{'year': '2017', 'month': '12', 'build_nr': '0027', 'tag': 'beta'}
>>> str(version)
201712.27b0
```
Lexical Ids
-----------
### Lexical Ids
Most projects will be served perfectly well by the default four
digit zero padded build number. Depending on your build system
@ -380,8 +366,7 @@ they are incremented in a way that preserves lexical ordering as
well as numerical order. Examples will perhaps illustrate more
clearly.
.. code-block:: python
```python
"0001"
"0002"
"0003"
@ -394,16 +379,17 @@ clearly.
"19999"
"220000"
"220001"
```
What is happening here is that the left-most digit is incremented
early, whenever the left-most digit changes. The formula is very simple:
.. code-block:: python
```python
prev_id = "0999"
next_id = str(int(prev_id, 10) + 1) # "1000"
if prev_id[0] != next_id[0]: # "0" != "1"
next_id = str(int(next_id, 10) * 11) # 1000 * 11 = 11000
```
In practice you can just ignore the left-most digit, in case you
@ -411,8 +397,7 @@ do want to read something into the semantically meaningless
build number.
Realities of Verion Numbers
---------------------------
### Realities of Verion Numbers
Nobody knows what the semantics of a version number are, because
nobody can guarantee that a given release adheres to whatever
@ -429,8 +414,7 @@ simple.
Some additional constraints are applied to conform with PEP440
Should I use PyCalVer for my Project?
-------------------------------------
### Should I use PyCalVer for my Project?
If your project is 1. not useful by itself, but only when used
by other software, 2. has a finite scope/a definition of "done",
@ -439,14 +423,12 @@ coverage, then PyCalVer is worth considering.
You release at most once per month.
Marketing/Vanity
----------------
### Marketing/Vanity
Quotes from http://sedimental.org/designing_a_version.html
Rational
--------
### Rational
PyCalVer is opinionated software. This keeps things simple,
when the opintions match yours, but makes it useless for
@ -477,8 +459,7 @@ foundations of other big shiny projects, which get to do their
big and exciting 2.0 major releases.
Breaking Things is a Big Deal
-----------------------------
### Breaking Things is a Big Deal
Using an increment in a version string to express that a release
may break client code is not tennable. A developer cannot be
@ -501,8 +482,7 @@ PyCalVer version strings can be parsed according to PEP440
https://www.python.org/dev/peps/pep-0440/
A Word on Marketing
-------------------
### A Word on Marketing
This setup of expectations for users can go one of two ways,
@ -512,8 +492,7 @@ for libraries, it pays to keep things as simple as possible for
your human users.
Commitment to Compatability
---------------------------
### Commitment to Compatability
Software projects can depend on many libraries. Consider that one
package introducing a breaking change is enough to mess up your
@ -566,11 +545,9 @@ https://calver.org/
from pkg_resources import parse_version
The Life of a Library
---------------------
.. code-block:
### The Life of a Library
```
mylib v201711.001-alpha # birth of a project (in alpha)
mylib v201711.002-alpha # new features (in alpha)
mylib v201712.003-beta # bugfix release (in beta)
@ -598,6 +575,7 @@ The Life of a Library
v202008.500 # 500 is the limit for four digit build numbers, but
v202008.508 # zero padding is added only after the turnover to
v202009.0509 # a new month, so that lexical ordering is preserved.
```
The date portion of the version, gives the user an indication of
@ -611,8 +589,7 @@ project that is only on build number 10, is probably still in
early development.
FAQ
---
### FAQ
Q: "So you're trying to tell me I need to create a whole new
package every time I introduce a introduce a breaking change?!".
@ -638,3 +615,36 @@ version number and 2. that users and packaging softare correctly
parse that meaning. When I used semantic versioning, I realized that
the major version number of my packages would never change,
because I don't think breaking changes should ever be
[build_img]: https://gitlab.com/mbarkhau/pycalver/badges/master/pipeline.svg
[build_ref]: https://gitlab.com/mbarkhau/pycalver/pipelines
[codecov_img]: https://gitlab.com/mbarkhau/pycalver/badges/master/coverage.svg
[codecov_ref]: https://mbarkhau.gitlab.io/pycalver/cov
[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_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
[pyversions_img]: https://img.shields.io/pypi/pyversions/pycalver.svg
[pyversions_ref]: https://pypi.python.org/pypi/pycalver

3
docker_base.Dockerfile
View file

@ -70,7 +70,8 @@ ADD makefile makefile
RUN make install
RUN rm /root/.ssh/id_rsa
RUN rm -f /root/.ssh/id_rsa
# Deleting pkgs implies that `conda install`
# will at have to pull all packages again.
RUN conda clean --all --yes

37
makefile
View file

@ -57,22 +57,20 @@ DEV_ENV_PY := $(DEV_ENV)/bin/python
build/envs.txt: requirements/conda.txt
@mkdir -p build/
@mkdir -p build/;
@if [[ ! -f $(CONDA_BIN) ]]; then \
if [[ $(PLATFORM) == "Linux" ]]; then \
echo "installing miniconda ..."; \
if [[ $(PLATFORM) == "Linux" ]]; then \
curl "https://repo.continuum.io/miniconda/Miniconda3-latest-Linux-x86_64.sh" \
-O build/miniconda3.sh; \
fi
if [[ $(PLATFORM) == "MINGW64_NT-10.0" ]]; then \
> build/miniconda3.sh; \
elif [[ $(PLATFORM) == "MINGW64_NT-10.0" ]]; then \
curl "https://repo.continuum.io/miniconda/Miniconda3-latest-Linux-x86_64.sh" \
-O build/miniconda3.sh; \
fi
if [[ $(PLATFORM) == "Darwin" ]]; then \
> build/miniconda3.sh; \
elif [[ $(PLATFORM) == "Darwin" ]]; then \
curl "https://repo.continuum.io/miniconda/Miniconda3-latest-MacOSX-x86_64.sh" \
-O build/miniconda3.sh; \
fi
> build/miniconda3.sh; \
fi; \
bash build/miniconda3.sh -b -p $(CONDA_ROOT); \
rm build/miniconda3.sh; \
fi
@ -94,7 +92,7 @@ build/envs.txt: requirements/conda.txt
build/deps.txt: build/envs.txt requirements/*.txt
@mkdir -p build/
@mkdir -p build/;
@SUPPORTED_PYTHON_VERSIONS="$(SUPPORTED_PYTHON_VERSIONS)" \
CONDA_ENV_NAMES="$(CONDA_ENV_NAMES)" \
@ -319,11 +317,12 @@ check: fmt lint mypy test
## Start shell with environ variables set.
.PHONY: env
env:
@bash -c '\
ENV=dev \
PYTHONPATH=\"src/:vendor/:$$PYTHONPATH\" \
PATH=\"$(DEV_ENV)/bin/:$$PATH\"; \
$$SHELL '
@bash --init-file <(echo '\
source $$HOME/.bashrc; \
export ENV=dev; \
export PYTHONPATH="src/:vendor/:$$PYTHONPATH"; \
conda activate $(DEV_ENV_NAME) \
')
## Drop into an ipython shell with correct env variables set
@ -411,12 +410,12 @@ build_docker:
--build-arg SSH_PRIVATE_RSA_KEY="$$(cat ${HOME}/.ssh/${PKG_NAME}_gitlab_runner_id_rsa)" \
--file docker_base.Dockerfile \
--tag $(DOCKER_REGISTRY_URL)/base:latest \
.
else
.; \
else \
docker build \
--file docker_base.Dockerfile \
--tag $(DOCKER_REGISTRY_URL)/base:latest \
.
.; \
fi
docker push $(DOCKER_REGISTRY_URL)/base:latest

1
requirements/integration.txt
View file

@ -20,5 +20,6 @@ pylint
twine
md-toc
straitjacket
pycalver