Usage examples
Init
Create the two punch_config.py
and punch_version.py
files if they are not existing.
punch --init
Standard invocation
Increase the minor
part and reset the following ones (e.g. 1.0.0 --> 1.1.0
)
punch --part minor
Explicitly set a part
Sets the minor
part to 23
and leave the following parts untouched (e.g. 1.2.3 --> 1.23.3
)
punch --set-part minor=23
Increment version and set a part
Increase the major
part, then reset the following ones. Finally set the minor
part to 23
leaving the following parts untouched (e.g. 1.2.3 (--> 2.0.0) --> 2.23.0
)
punch --part major --set-part minor=23
Explicitly set and reset
Set the minor
part to 23
and reset the following parts (e.g. 1.2.3 --> 1.23.0
)
punch --set-part minor=23 --reset-on-set
Examples
The following are examples of Punch configuration that show the different options implemented in it. The configuration files are all implemented in working tests that you can find in the test_config_*.py
files of the test suite.
Plain SemVer
This is an example configuration that uses SemVer (http://semver.org) without any metadata (as described by parts 9 and 10 of the specification).
__config_version__ = 1
GLOBALS = {
'serializer': '{{major}}.{{minor}}.{{patch}}'
}
FILES = []
VERSION = ['major', 'minor', 'patch']
Part updated | Current version | New version |
---|---|---|
major | 1.0.0 | 2.0.0 |
minor | 1.0.0 | 1.1.0 |
patch | 1.0.0 | 1.0.1 |
CalVer Ubuntu-style
This example uses a versioning style taken from Ubuntu, which uses the CalVer 'YY.MM' syntax, that is the current year and the current month without zero-padding. See here for the CalVer explanation.
__config_version__ = 1
GLOBALS = {
'serializer': '{{year}}.{{month}}',
}
FILES = ["README.md"]
VERSION = [
{
'name': 'year',
'type': 'date',
'fmt': 'YY'
},
{
'name': 'month',
'type': 'date',
'fmt': 'MM'
}
]
Part updated | Current version | New version |
---|---|---|
year | 2016 | current(1) |
month | 10 | current(2) |
(1) uses the current unpadded year, like 4
if the current year is 2004, 17
is the current year is 2017, and so on.
(2) uses the current unpadded month, so one of the values in the list [1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12]
SemVer with build metadata
This configuration implements SemVer with build metadata (as described by part 10 of the specification). This build number is made of three digit and starts with 1
__config_version__ = 1
GLOBALS = {
'serializer': "{{ major }}.{{ minor }}.{{ patch }}{{ '+{0:03d}'.format(build) }}"
}
FILES = ["README.md"]
VERSION = [
'major',
'minor',
'patch',
{
'name': 'build',
'type': 'integer',
'start_value': 1
}
]
Part updated | Current version | New version |
---|---|---|
major | 1.0.0+001 | 2.0.0+001 |
minor | 1.0.0+001 | 1.1.0+001 |
patch | 1.0.0+001 | 1.0.1+001 |
build | 1.0.0+001 | 1.0.0+002 |
SemVer with prerelease metadata
This configuration implements SemVer with prerelease metadata (as described by part 9 of the specification). The chosen prerelease strings are 'alpha'
and 'beta
.
WARNING: This use of the prerelease parts is pretty incomplete and a bit useless. It will be soon updated
__config_version__ = 1
GLOBALS = {
'serializer': "{{ major }}.{{ minor }}.{{ patch }}{{ '-{}'.format(prerelease) if prerelease }}"
}
FILES = ["README.md"]
VERSION = [
'major',
'minor',
'patch',
{
'name': 'prerelease',
'type': 'value_list',
'allowed_values': ['', 'alpha', 'beta']
}
]
Part updated | Current version | New version |
---|---|---|
major | 1.0.0-alpha | 2.0.0 |
minor | 1.0.0-alpha | 1.1.0 |
patch | 1.0.0-alpha | 1.0.1 |
prerelease | 1.0.0-alpha | 1.0.0-beta |
prerelease | 1.0.0-beta | 1.0.0 |
When using tags like the prerelease shown here you may take advantage of the --set-part
option that allows to explicitly set the value of a version part when creating the new version.
If you put the empty string as last element of the string you get the following behaviour
__config_version__ = 1
GLOBALS = {
'serializer': "{{ major }}.{{ minor }}.{{ patch }}{{ '-{}'.format(prerelease) if prerelease }}"
}
FILES = ["README.md"]
VERSION = [
'major',
'minor',
'patch',
{
'name': 'prerelease',
'type': 'value_list',
'allowed_values': ['alpha', 'beta', '']
}
]
Part updated | Current version | New version |
---|---|---|
major | 1.0.0-alpha | 2.0.0-alpha |
minor | 1.0.0-alpha | 1.1.0-alpha |
patch | 1.0.0-alpha | 1.0.1-alpha |
prerelease | 1.0.0-alpha | 1.0.0-beta |
prerelease | 1.0.0-beta | 1.0.0 |