Warning
THIS IS ALPHA GRADE SOFTWARE. PLEASE READ CAREFULLY THE PRESENT DOCUMENTATION
Table of Contents
You may use it entirely from the CLI, but it may not be advised for projects. The cli is just htere for convenience.
It is intended to be used via a configuration file, by default named version.conf
Here is the one used for this module:
{
"files": "auto_version/main.py",
"current_version": "0.1.0",
"style": "Triplet"
}
The style option is a string representing the name of the style class to use. Here, I use the Triplet format, which consists in <major>.<minor>.<patch>.
"files" may be a simple string, or an array, like this:
{
"files": [
"path/to/file",
"other/path/to/file"
],
other stuff,
blablabla
}
See auto_version.styles for more available version string styles.
Warning
This is still a rather unstable feature, your workflow may be changed, and possibly destroyed.
If versioning system is detected (via the presence or not of a distinctive versioning directory, like .git), auto-version uses the informations present in the SCM to determine the version numbers. For git, it is via the git tag and git describe commands;
This still requires a version.conf file, but only three parameters are used:
{
"files": "file_to_manage",
"style": "Triplet",
"scm_prefix": "prefix to use for version tagging"
}
$ cd /tmp
$ git init testing
$ cd testing
$ echo "0.0.1" > hello.txt
$ echo '{ "files": "hello.txt", "style": "Triplet, "scm_prefix": ""}' > version.conf
$ git add hello.txt version.conf
$ git commit -m "Initial commit"
$ git tag 0.0.1
$ auto-version update
$ cat hello.txt
0.0.1
$ echo "hi\!" >> hello.txt
$ git add hello.txt
$ git commit -m "Modified hello.txt to better reflect my understanding of the world, from a programmer\'s perspective"
$ auto-version update
$ cat hello.txt
0.0.2-pre1-0bf45de
hi!
$ auto-version patch
$ cat hello.txt
0.0.2
hi!
auto_version.styles is the holder of all the different coding styles.
Each style is built on top of others, as they have multiple features in common. For instance, a Revision-based versioning has a feature used in <major>.<minor>.
I am still thinking about it.
This is the base style every Style class should inherit from.
Double format is in the form <major>.<minor>
It is pretty self-explainatory. Mostly used in very small projects, without a lot of dependencies.
<major> begins most of the time at 0, indicating the in-development state of the project.
Full format, aka. :<major>.<minor>.<patch>+<status>-<build> where <major>, <minor>, <patch> and <build> are numbers (aka, the actual version number. Well, except for the build number), and <status> is one of the following:
- prealpha
- alpha
- beta
- rc
- release
Warning
NOT YET IMPLEMENTED!
Revision format is a simple, one-number versioning format: r<number> for instance, r7 is the version after r6.
It is used in some DCVS, such as mercurial, or svn.
Trpilet format is in the form <major>.<minor>.<patch>
It is the most commonly used versioning ‘style’.
Performs increment of version number, according to the given “level” parameter.
Level may be one of the followings:
- “patch” or 2: increments the <patch> part of the version string
- “minor” or 1: increments the <minor> part of the version string, and resets <patch> to 0
- “major” or 0: increments the <major> part of the version string, and resets <minor> and <patch> to 0
This modules contains all the implementation for versioning system automation.
see Issue#1
The resulting version number will be in the form <ChosenStyle>+<VCSStyle>.
For git, VCSStyle is in the form pre<number_of_commits_since_last_tag>-<sha_hash_of_last_commit>-<is_dirty?>
If the user wants to use DVCS system, the option –use-vcs should be present, or “use_vcs”: True should be present in config. This way, people won’t find creepy hashes in their version string.
This module contains the main Parser class. This class is the one parsing the given files, and replacing the values by the new ones.
This Class is a basic parser. It takes a list of files in argument, and the format of the versioning system, and performs the replacement.
Contains some utilities used in the project. You should not have to bother with it.
Configuration manager. It makes the bridge and the intelligence between the cli args and the configuration file, who may be present. Or not. Whatever.
The conf variable is a dictionnary, loaded from a json file.