To avoid misunderstanding the following small vocabulary is established:

Project

the project you are working on. Includes source code, documentation and other auxillary files.

Module

part of the project with individual versioning scheme. Large or complex projects often release several independant modules, each with it's own versioning scheme. Simple projects typically defines single module, whose version is used as a project version.

Versioning scheme

format of the version (or naming) scheme used to enumerate project's releases. A scheme is consists from a number of components.

Version component

A logical part of the version.

Dependant files

files that must be updated by Vertoo when module's version is changed.

Design and architecture

A central notion in Vertoo is version. Project is viewed as one or more modules each of them having it's own version. Along with version, each module contains a list of files which would be updated by the Vertoo and optional SCM configuration if you going to use some SCM system like CVS.

Version is defined as an ordered list of components, or version parts. A part has value (like 2 or pre1) and type. Currently, only two types are supported: basic and missing. You could change part's value with Vertoo commands set and set-part.

Basic type could store number or arbitrary string value. If value is a number then you could increment it. "Missing" type is supposed to be used as a placeholder for part which has no value now but may have had a value later. For example, suppose you release versions 1.1, 1.2, etc. but when a critical bug is fixed you could release version 1.2.1. To describe this configuration you could define part "release" of type "missing".

Vertoo also supports part's dependencies. This means that you can declare, for example: "reset minor part when major is incremented" or "reset build part when any part is incremented". Dependencies are described in your configuration file.

Configuration is specified with two files: vertoo.data, with current version information, and vertoo.config which describes project's modules, their versioning schemes and dependent files.

At the beginning you must create these two files by hand. Afterwards, file vertoo.data would be automatically updated by Vertoo and file vertoo.config does not need changes at all. Unless, of course, you want to make changes to your project's configuration. Then you'll need to update one or both of these files again.

When you describe your project's configuration there is a number of places that requires a version template that is evaluated at run-time for particular version string. It's semantic is similar to the ubiquitous printf, albeit a bit more complex due to conditinals and recursive expansions.

The following text sequences have the special meaning in the template:

• %name expands to the value of the part named "name"
• @name expands to the (recursively) formatted value of the scheme named "name" from the registry
• %[name?a:b] expands to a if the part named "name" has a value (i.e. it's not a "missing" part) or to b if that part is "missing".
• @. expands to the name of the module which this version describes
• @- expands to the full version string except the missing parts
• @+ expands to the full version string including missing parts, which are represented by x
• @@ expands to the single @ symbol.
• %% expands to the single % symbol.

• parameter format of the FileInfo's anchors
• parameter commitmsg and tagfmt of the ScmToolInfo

This file contains current values of the version's components for each of the project module.

Empty lines and lines starting with # are ignored. Each non-empty line must have the following format:

  <module-name> = <part-name>:<part-value>; [<part-name>:<part-value>;]+

Module name and part names are case insensitive while part's values are case sensitive. Any number of whitespace characters are allowed around = sign and between parts. Note, however that whitespace (if any) between : and ; are considered to be a part of the <part-value>.

A part value x or none denotes "missing" part. Any other string value defines a part of type "basic".

Currently this is plain Python script which is evaluated by Vertoo at run-time. I'm planning to implement a "real" configuration language a bit later, when I would know enough about what and how will be described. Introduction of the configuration language would mean the end to the alpha-version period as well.

There is no documentation yet, please see vertoo.config from the distribution or the example below.

Vertoo is run by the vertoocmd.py script. There are a number of commands and options available, which you could see by running vertoocmd.py without arguments.

Basically, commands can be divided into several groups:

Status commands

show, check

Operational commands

incr, set, set-part

SCM integration

tag, commit

If you have several modules in your project option -m/--module allows to select one or more module to work with (by default all modules are processed). For some commands (set and set-part) you would almost always have to use this option because different modules usually use different versioning schemes and these commands' arguments depend on it.

Option -d/--show-diff would allow you to see changes that are made in files. Option -v/--verbose is useful when you encounter a problem or want to track Vertoo's bug. When used, more debug information is printed and full Python traceback is printed in case of errors.

Suppose we have a project Foobar of version 0.8.3 and files main.c and README includes version info that we would like to be updated automatically by Vertoo.

Here are the configuration files that must be created:

vertoo.data

    foobar = major:0; minor:8; release:3

vertoo.config

   registry.registerScheme('full', '%major.%minor.%release')
   
   main = ModuleInfo('foobar', [
     FileInfo("README", [
       AnchorInfo('simple', 1,
         arguments(pattern="Foobar %v", format="%major.%minor")),
       ]),
     FileInfo("main.c", [
       AnchorInfo('simple', 1,
         arguments(pattern="version[] = %Q;", format="@full")),
       ]),
     ])
   
   modules = [main]

Notice that version components could be reffered with %name syntax and to specify text that must match in a file use %v, %q or %Q syntax (this corresponds to version string plain, in single quotes and in double quotes).

After these files are created you could use vertoocmd.py to update version data (using incr or set commands). File vertoo.data would be automatically updated by Vertoo, as well as dependant files

   $ vertoocmd.py incr minor
  
   increment module main version from 0.8.3 to 0.9.1
   Update files with version 0.9.1 OK
  
   $ cat README
   
   This is Foobar 0.9.
  
   $ grep version main.c
   const char* version[] = "0.9.1";