Development tool for configuring and altering software versions.
Project description
MyVer
MyVer is a tool to help you manage and alter your project's version number. You can define your own configuration for your version, MyVer gives you complete freedom to enforce your own version spec, make it as simple or as complex as you need it to be.
Table of Contents
- Installation
- Usage
- Configuration
- YAML Syntax
files
files[*].path
files[*].patterns
parts
parts.<part>
parts.<part>.value
parts.<part>.requires
parts.<part>.prefix
parts.<part>.identifier
parts.<part>.identifier.strings
parts.<part>.identifier.start
parts.<part>.number
parts.<part>.number.label
parts.<part>.number.label-suffix
parts.<part>.number.start
parts.<part>.number.show-start
- YAML Syntax
- Examples
Installation
To install MyVer you can use pip, which will download and install the MyVer package from PyPi
pip install myver
Usage
Usage: myver [OPTIONS]
Options:
-h, --help Show this help message and exit
-b, --bump strings Bump version parts
--config string Config file path
-c, --current [strings] Get the current version or version parts
-r, --reset strings Reset version parts
-v, --verbose Log more details
Configuration
This section will describe the configurations YAML syntax. This is for a detailed explanation of each attribute in the configuration. While examples may be present in this section, it is also beneficial to refer to the Examples section to see full practical implementations of the configuration YAML.
YAML Syntax
files
Optional. A list of files to update when the version is changed. It will only change references to the current version value by default.
An unwanted file change is possible if you are referencing the version
of another project in a file that happens to have the same version
string as your project, then both instances of that version string will
be updated. So lets say your project's version is 3.6.8
and you are updating a file that is referencing Python 3.6.8
, then by
default the python version reference will be updated. Although these
unwanted file updates can be avoided with further configuration.
files:
- path: 'setup.py'
patterns:
- "version='{{ version }}'"
- path: '/project/__version__.py'
files[*].path
The path to a file that you want to update with each version change. This path can use globbing so that you can define a range of files to update.
files:
- path: '/path/to/file.md'
- path: '/can/also/glob/*.txt'
files[*].patterns
List of regex patterns to use for updating a file. Any instance of a
version string will not be updated if it does not match a pattern. The
pattern regex strings must contain {{ version }}
to parse the current
version into the pattern, this will be parsed first before the regex is
utilised in searching for file updates. We need to include
{{ version }}
because this signifies the part of the string to change
in a pattern match.
If files[*].patterns
is not configured, it is assumed that the default
pattern match is just {{ version }}
, meaning that any string in the
file that is equal to the current version will be updated.
files:
- path: 'setup.py'
patterns:
- "version='{{ version }}'"
parts
Required. Collection of parts configured for your project's version.
You must define at least 1 parts.<part>
in this
collection.
parts.<part>
The configuration of an individual part in a version. You define the key
of the part through the name of the YAML attribute, in the example
below the key of our only part is major
, you can name these keys
whatever you like, although you cannot have 2 parts with the same key
name.
There are 2 types of parts -- identifier parts and number parts. An
identifier part is a string part that can have a value based on a range
of strings, see parts.<part>.identifier
.
Whereas a number part is simply a positive integer that can be
incremented. The number part is the default type if a type is not
explicitly configured.
parts:
major:
value: 3
parts.<part>.value
Each part configuration needs to define a value attribute in its spec.
If your part has no value then use value: null
. Depending on the part
type, the value of the part can be a string or a number. All parts can
also be null
.
parts:
major:
value: 3
minor:
value: null
pre:
value: 'beta'
identifier:
strings: [ 'beta' ]
parts.<part>.requires
Defines a part that is required to exist by another part. It means that
if a part has a non-null value, and it requires another part, the part
that it requires cannot be null. In the example below we see that
major
requires minor
, this means that minor
can only ever be null
if major
is null. So if major
has a non-null value, then minor
must also have a non-null value.
parts:
major:
value: 3
requires: 'minor'
minor:
value: 9
parts.<part>.prefix
A string to display before the part. In the example below we have part
major
and minor
, if we parse this version we will get 3.9
, where
the .9
is the minor
part where the .
is the prefix of the part's
value.
parts:
major:
value: 3
minor:
value: 9
prefix: '.'
parts.<part>.identifier
When this is configured on a part, it signifies that the part value is
a string. You cannot configure parts.<part>.identifier
and
parts.<part>.number
at the same time, they are
mutually exclusive.
You would use this when you have multiple possible strings for a part
that have a chronological order between each string. A common example
are the pre-release identifiers of alpha
, beta
, and rc
.
parts.<part>.identifier.strings
A list of strings to be used in the part's value, if you have configured
parts.<part>.identifier
for a part, then this
list of strings needs to be configured. The order of the strings matter
as the bumping of an identifier part will move through the list in the
order it is defined.
parts:
pre:
identifier:
strings:
- 'alpha'
- 'beta'
- 'rc'
parts.<part>.identifier.start
The starting value for the part. The start value is the value that the
part will use when it is bumped from a null
value, or when it is
reset. By default, if this is not configured explicitly, the start value
is assumed to be the first value in the
parts.<part>.identifier.strings
list.
parts:
pre:
value: 'beta'
identifier:
strings:
- 'alpha'
- 'beta'
- 'rc'
start: 'beta'
parts.<part>.number
This will configure a part to be a positive integer. You cannot
configure parts.<part>.identifier
and
parts.<part>.number
at the same time, they are mutually exclusive.
parts.<part>.number.label
Sometimes you will want a label for a number part. In the example below
we have a build
part, instead of just using a number to represent this
part, you may instead want to parse it to something like build4
, and
this is what the example below achieves.
parts:
build:
value: 4
number:
label: 'build'
parts.<part>.number.label-suffix
A label may have a suffix (characters after the label) in order to
separate the label with the number. In the example below we see the .
suffix on a build
label, which would give something like build.4
when it is parsed.
parts:
build:
value: 4
number:
label: 'build'
label-suffix: '.'
parts.<part>.number.start
This defines the starting value for a number part, this the value that
the part will use when it is bumped out of a null
value, or if it is
reset. By default, it is assumed that the start value of a number part
is 0
if it is not configured explicitly.
parts:
build:
value: 4
number:
start: 1
parts.<part>.number.show-start
Sometimes you may not want to show the first value of a number part. In
the example below we have a dev
part, commonly you may see a version
like 3.4.5+dev
which would define the first dev instance of a version,
then the second dev instance would look like this 3.4.5+dev.2
. By
default, this value will be assumed to be true
if it is not
configured explicitly.
parts:
dev:
value: 1
number:
label: 'dev'
label-suffix: '.'
start: 1
show-start: false
Examples
SemVer
This file handles how the version is formed. It will store the current values of each part, and it will also define the configuration of each part.
parts:
major:
value: 3
requires: minor
minor:
value: 9
prefix: '.'
requires: patch
patch:
value: 2
prefix: '.'
pre:
value: null
prefix: '-'
requires: prenum
identifier:
strings: [ 'alpha', 'beta', 'rc' ]
prenum:
prefix: '.'
value: null
number:
start: 1
build:
value: null
prefix: '+'
number:
label: 'build'
label-suffix: '.'
start: 1
dev:
value: null
prefix: '+'
number:
label: 'build'
label-suffix: '.'
start: 1
show-start: false
Preamble
In each of these scenarios we will show a snippet which is demonstrating how you may interact with MyVer in a terminal environment. There may then be a description of what is happening in the snippet demonstration below each snippet.
Standard bumping scenarios
➜ myver --current
3.8.2
➜ myver --bump patch
3.8.2 >> 3.8.3
➜ myver --bump minor
3.8.3 >> 3.9.0
Custom parsing of the version
➜ myver --current
3.8.2
➜ myver --current major minor
3.8
Sometimes you may want to parse the version with specific parts only.
There are many case by case reasons for this, but one case is to use
this for docker image tagging. In the example above if we do not specify
what parts to parse then the whole version is parsed. Although we can
specify the parts to parse as seen above with major
and minor
being
parsed in the second command, resulting in 3.8
.
➜ myver --current major minor prenum
3.8
➜ myver --bump pre
3.8.2 >> 3.8.2-alpha.1
➜ myver --current major minor prenum
3.8.2-alpha.1
We can also include a part that may not be set. In the example above
we include prenum
part to be parsed, although it is not set which
means it is ignored, so the remaining parts that are specified and
set will be parsed.
After setting the prenum
value though, running the same command will
result in parsing every part that is set between minor
and prenum
.
While our command only specifies major
, minor
and prenum
, it does
not mean to only parse these values, think of them as ranges instead,
so we are parsing major
to minor
, and then minor
to
prenum
.
Bumping with non-required child
➜ myver --current
3.8.2
➜ myver --bump patch dev
3.8.2 >> 3.8.3+dev
In this example we show how the part ordering matters in the config. We
can see that the dev
part is configured after the patch
part, and
the patch
part does not require any other part. This means that dev
is a valid child for the patch
part.
➜ myver --current
3.8.3+dev
➜ myver --bump patch
3.8.3+dev >> 3.8.4
It is also important to keep in mind that non-required child parts will
be removed when its parent is bumped if you do not ask to keep the child
part. In the above example we bump patch
and the dev
part gets
removed, if we wanted to have the dev
part in the bumped version then
we would have to be more explicit and use myver --bump patch dev
.
Part with a required child
➜ myver --current
3.8.2
➜ myver --bump patch pre
3.8.2 >> 3.8.3-alpha.1
We see that specifying pre
to be brought along with the bump of
patch
, also brings along prenum
. This is because prenum
is
configured to be required by pre
.
Also note that having a null part and attempting to bump it will set it
at its starting value, and it will bring along its required child if it
has one. A starting value by default is the first value in the list of
its strings
in the identifier
configuration. In this case we see
that pre
starts with the value of alpha
. If it is a number part then
the start value is 0
by default.
Value overriding
➜ myver --current
3.8.2
➜ myver --bump minor pre=beta
3.8.2 >> 3.9.0-beta.1
➜ myver --bump patch=5
3.9.0-beta.1 >> 3.9.5
Sometimes you may not want to use the start value of a string part. Here
we see that pre
is an identifier part (which is implied through having
its identifier
configuration). By providing the '='
character and a
valid identifier directly after pre
, it will use that identifier value
for the pre
part, in this case it is beta
, which is skipping
the alhpa
value. It is important that you specify a part value that is
valid (i.e. it is in the strings
list in the identifier
configuration of the part)
We can also do the same for number parts, above we see that we used
value overriding to set patch
to 5
. For a number part, you cannot
set the value to a negative number, and it cannot be a string either, it
must be an integer.
Resetting optional part
➜ myver --current
3.9.0-beta.1+build.34
➜ myver --reset pre
3.9.0-beta.1+build.34 >> 3.9.0
You may want to remove a part, this can easily be done with the
--reset
option. In the above scenario we see that resetting an
optional part will also reset its descendants. Although we can keep a
descendant if we use --bump
.
➜ myver --current
3.9.0-beta.1+build.34
➜ myver --reset pre --bump build
3.9.0-beta.1+build.34 >> 3.9.0
3.9.0 >> 3.9.0+build.1
Implicit children
This may not even need to be explained as it is supposed to be intuitive, although I am including this section just to explain the implicit children in a technical way so that people can debug any of their use cases which may be acting weird due to this feature. So you do not have to understand this section to make use of implicit children, it should hopefully come to you naturally.
➜ myver --current
3.8.2+build.1
➜ myver --bump dev
3.8.2+build.1 >> 3.8.2+build.1-dev
This is the clearest example of implicit children, in the config we do
not explicitly define the dev
part to be required by the buildnum
part, yet it becomes a child of buildnum
when we add dev
in a bump.
This is due to the order of the parts in the config, and also due to
dev
not being a required child of any other parts, so the only logical
place to put the dev
part is after the last part that has a value,
which in this case is buildnum
.
➜ myver --current
3.8.2+build.1-dev
➜ myver --bump buildnum
3.8.2+build.1-dev >> 3.8.2+build.2
Also keep in mind that implicit children will be removed if their parent
is bumped. In the above example if you wanted to keep dev
you need to
be explicit and use myver --bump buildnum dev
➜ myver --current
3.8.2
➜ myver --bump patch pre dev
3.8.2 >> 3.8.3-alpha.1+dev
When bumping patch
with pre
, the pre
will bring along its prenum
child since it is a required part. Although how did we bring along dev
with prenum
if we do not specify prenum
in the arguments of the
command? In this scenario we can say that dev
is implicitly a child of
the prenum
part, and this happens due to prenum
being a required
child of pre
, and prenum
is also defined before the dev
part is
defined in the config, so it takes precedence.
So why are we allowed to ignore the build
part? It's because
the build
part is not required by any other part that is current set.
➜ myver --current
3.8.3-alpha.1+dev
➜ myver --bump build
3.8.3-alpha.1+dev >> 3.8.3-alpha.1+build.1
Why did the dev
part get removed in this case? This is because of the
ordering of the parts in the config. When an implicit parent-child
relationship is broken, the original child part is removed. In this
scenario the prenum
and dev
implicit relationship is broken because
adding the build
and buildnum
part introduces a new implicit child
for prenum
. The build
part is defined in the config before dev
is
defined, so it takes precedence, which is why we do not get a new
version of something like 3.8.3-alpha.1+dev-build.1
This scenario is a simple config, so it may be reasonable to think that
we should just keep the dev
and make it a child of the buildnum
part, but what happens in more complex scenarios with many possible
implicit children? Also, it is not a good thing to freely shift parts
around as a side effect of bumping other parts, the command should
explicitly ask for a version outcome. In other words, having dev
as a
child of one part, has no chronological relation with a different part
having dev
as its child, they are both dev instances of completely
different versions. Since myver --bump build
does not explicitly ask
for dev
to be in the bumped version, then we should not provide a
version that is not explicitly asked for.
Project details
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.