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

release preparation

Browse source
This commit is contained in:
Manuel Barkhau 2018-12-05 09:37:34 +01:00
parent 0095f974da
commit 70f4e01104
9 changed files with 145 additions and 107 deletions
Download patch file Download diff file Expand all files Collapse all files

192
README.md
View file

@ -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 | - |
<!--
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
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=<tag>` 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