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

readme updates

Browse source
This commit is contained in:
Manuel Barkhau 2018-11-06 21:43:34 +01:00
parent 2e20d8d364
commit 3385f2d675
1 changed files with 116 additions and 123 deletions
Download patch file Download diff file Expand all files Collapse all files

239
README.md
View file

@ -1,11 +1,11 @@
# PyCalVer: Automatic CalVer Versioning for Python Packages # PyCalVer: Automatic CalVer Versioning for Python Packages
PyCalVer is a very simple versioning system, which is compatible PyCalVer is a simple versioning system, which is compatible
with python packaging software with python packaging software
[setuptools](https://setuptools.readthedocs.io/en/latest/setuptools.html#specifying-your-project-s-version>) [setuptools](https://setuptools.readthedocs.io/en/latest/setuptools.html#specifying-your-project-s-version>)
[PEP440](https://www.python.org/dev/peps/pep-0440/). [PEP440](https://www.python.org/dev/peps/pep-0440/).
[![Build Status][ci_build_img]][ci_build_ref] [![Build Status][build_img]][build_ref]
[![Code Coverage][codecov_img]][codecov_ref] [![Code Coverage][codecov_img]][codecov_ref]
[![MIT License][license_img]][license_ref] [![MIT License][license_img]][license_ref]
[![Code Style: sjfmt][style_img]][style_ref] [![Code Style: sjfmt][style_img]][style_ref]
@ -29,34 +29,33 @@ with python packaging software
[](TOC) [](TOC)
- [PyCalVer: Automatic CalVer Versioning for Python Packages](#pycalver-automatic-calver-versioning-for-python-packages) - [Introduction](#introduction)
- [Introduction](#introduction) - [Versioning Behaviour](#versioning-behaviour)
- [https://regex101.com/r/fnj60p/10](#https-regex101-com-r-fnj60p-10) - [Lexical Ids](#lexical-ids)
- [Usage](#usage) - [Usage](#usage)
- [Installation](#installation) - [Installation](#installation)
- [Configuration](#configuration) - [Configuration](#configuration)
- [Pattern Search and Replacement](#pattern-search-and-replacement) - [Pattern Search and Replacement](#pattern-search-and-replacement)
- [Other Versioning Software](#other-versioning-software) - [Other Versioning Software](#other-versioning-software)
- [Rational](#rational) - [Rational](#rational)
- [Some Details](#some-details) - [Some Details](#some-details)
- [Lexical Ids](#lexical-ids) - [Realities of Verion Numbers](#realities-of-verion-numbers)
- [Realities of Verion Numbers](#realities-of-verion-numbers) - [Should I use PyCalVer for my Project?](#should-i-use-pycalver-for-my-project)
- [Should I use PyCalVer for my Project?](#should-i-use-pycalver-for-my-project) - [Marketing/Vanity](#marketing-vanity)
- [Marketing/Vanity](#marketing-vanity) - [Rational](#rational-1)
- [Rational](#rational-1) - [Breaking Things is a Big Deal](#breaking-things-is-a-big-deal)
- [Breaking Things is a Big Deal](#breaking-things-is-a-big-deal) - [A Word on Marketing](#a-word-on-marketing)
- [A Word on Marketing](#a-word-on-marketing) - [Commitment to Compatability](#commitment-to-compatability)
- [Commitment to Compatability](#commitment-to-compatability) - [The Life of a Library](#the-life-of-a-library)
- [The Life of a Library](#the-life-of-a-library) - [FAQ](#faq)
- [FAQ](#faq)
[](TOC) [](TOC)
## Introduction ## Introduction
The PyCalVer package provides the `pycalver` command and The PyCalVer package provides the `pycalver` command and module
module to generate version strings which follow the following to generate version strings. These use the following format:
format: `v{calendar_version}.{build_number}[-{release_tag}]` `v{calendar_version}.{build_number}[-{release_tag}]`
Some examples: Some examples:
@ -70,12 +69,13 @@ v202207.18133
v202207.18134 v202207.18134
``` ```
The `pycalver bump` command will parse the files you configure The `pycalver bump` command parses your files for such strings
in `setup.cfg` for such strings and rewrite them with an and rewrites them with an incremented version string.
updated version string.
The format accepted by PyCalVer can be parsed with this regular ### Format
expression:
The format for PyCalVer version strings can be parsed with this
regular expression:
```python ```python
import re import re
@ -125,34 +125,89 @@ assert version_info == {
} }
``` ```
## Usage ### Versioning Behaviour
### Installation To illustrate how PyCalVer increments version strings, we can use
`pycalver incr`:
Before we look at project setup, we can simply install and test
by passing a version string to `pycalver incr`.
```shell ```shell
$ pip install pycalver $ pip install pycalver
...
$ pycalver incr v201801.0033-beta $ pycalver incr v201801.0033-beta
PyCalVer Version: v201809.0034-beta PyCalVer Version: v201809.0034-beta
PEP440 Version: 201809.34b0 PEP440 Version: 201809.34b0
```
This is the simple case:
- The calendar component is update to the current year and month.
- The build number is incremented by 1.
- The optional release tag is preserved as is.
Here is how to explicitly update the release tag:
```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 incr v201801.0033-beta --release=final
PyCalVer Version: v201809.0034 PyCalVer Version: v201809.0034
PEP440 Version: 201809.34 PEP440 Version: 201809.34
$ pycalver incr v201809.1999
PyCalVer Version: v201809.22000
PEP440 Version: 201809.22000
``` ```
The CalVer component is set to the current year and month, the The version number is padded with extra zeros, to maintain the
build number is incremented by one and the optional release tag lexical ordering of version numbers. What happens when the
is preserved as is, unless specified otherwise via the padding is exhausted?
`--release=<tag>` parameter.
```shell
$ pycalver incr v201809.0999
PyCalVer Version: v201809.11000
PEP440 Version: 201809.11000
```
This is because the build number is generated as a sequence of
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.
```python
"0001"
"0002"
"0003"
...
"0999"
"11000"
"11001"
...
"19998"
"19999"
"220000"
"220001"
```
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:
```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
```
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.
## Usage
### Configuration ### Configuration
@ -169,9 +224,6 @@ Updated setup.cfg
This will add the following to your `setup.cfg`: This will add the following to your `setup.cfg`:
```ini ```ini
[bdist_wheel]
universal = 1
[pycalver] [pycalver]
current_version = v201809.0001-dev current_version = v201809.0001-dev
commit = True commit = True
@ -192,11 +244,9 @@ patterns =
{pep440_version} {pep440_version}
``` ```
Depending on your project, the above will probably cover all This may or may not cover all version numbers across your
version numbers across your repository. Something like the repository. Something like the following may illustrate
following may illustrate additional changes you might need to additional changes you might need to make.
make.
```ini ```ini
[pycalver] [pycalver]
@ -222,20 +272,16 @@ patterns =
img.shields.io/badge/PyCalVer-{calver}{build}--{release}-blue img.shields.io/badge/PyCalVer-{calver}{build}--{release}-blue
``` ```
If `patterns` is not specified for a `pycalver:file:` You can ommit `patterns` if the default patterns are sufficient.
section, the default patterns are used: These are:
```ini ```ini
[pycalver:file:src/myproject.py]
patterns = patterns =
{version} {version}
{pep440_version} {pep440_version}
``` ```
This allows for a less explicit but shorter configuration, like This allows for a shorter (albeit less explicit) configuration:
this:
```ini ```ini
[pycalver] [pycalver]
@ -290,37 +336,24 @@ Current Version: v201809.0001-beta
PEP440 Version: 201809.1b0 PEP440 Version: 201809.1b0
$ pycalver bump --dry $ pycalver bump --dry
TODO: diff output
Dont forget to do $ git push --tags Dont forget to do $ git push --tags
``` ```
### Other Versioning Software TODO: commits and tags
This project is very similar to bumpversion, upon which it is
partially based, but since the PyCalVer version strings can be
generated automatically, usage is quite a bit more simple. Users
do not have to deal with parsing and generating version strings.
Most of the interaction that users will have is reduced to two
commands:
```shell
$ pycalver bump
TODO: Output
```
More rarely, when changing the release type:
```shell
$ pycalver bump --release beta
TODO: Output
$ pycalver bump --release final
TODO: Output
```
## Rational ## Rational
### Other Versioning Software
This project is very similar to
[bumpversion](https://github.com/peritus/bumpversion), upon which
it is partially based. So why another library?
PyCalVer version strings can be
generated automatically, usage is a bit more simple.
### Some Details ### Some Details
- Version numbers are for public releases. For the purposes of - Version numbers are for public releases. For the purposes of
@ -356,46 +389,6 @@ In [2]: version_dict
``` ```
### Lexical Ids
Most projects will be served perfectly well by the default four
digit zero padded build number. Depending on your build system
however, you may get into higher build numbers. Since build
numbers have no semantic meaning (beyond larger = later/newer),
they are incremented in a way that preserves lexical ordering as
well as numerical order. Examples will perhaps illustrate more
clearly.
```python
"0001"
"0002"
"0003"
...
"0999"
"11000"
"11001"
...
"19998"
"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:
```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
do want to read something into the semantically meaningless
build number.
### Realities of Verion Numbers ### Realities of Verion Numbers