Conary:Version String

From rPath Wiki

The version string of a trove (such as a group, package, or component), along with its flavor, identifies the trove as a unique part of a Conary repository. The version string can be a rather complex string of characters to read, but it contains a lot of useful information such as the current branch on which the trove resides, parent branches from which it was shadowed, and revision information for its source and build.

A full version string begins with a slash (/) and ends with a revision number. Parts of the version string can be used to identify the trove in some scenarios when the full version string is not needed. However, the full version string ensures that Conary does not fill in any missing parts with default values. The following is an example of a full version string used to identify a particular revision of group-example:
group-example=/example.rpath.org@corp:example-1-devel//
example.rpath.org@corp:example-1-test//example.rpath.org@corp:example-1//1.0-2-1

To see the full version string of a trove, use --full-versions with conary query and conary repquery commands:

$> conary q timescript --full-versions
timescript=/example.rpath.org@corp:devel/1.0-2-1
$> conary rq timescript=example.rpath.org@corp:devel --full-versions
timescript=/example.rpath.org@corp:devel/1.0-2-1

The version string "anatomy" includes the parts shown in this image and described in the following sections:

Branch

A Conary branch identifies a development path. A branch is written with a preceding slash (/) and includes the labels on which the branch resides.

If the branch has multiple labels separated by double slashes (//), each subsequent label is a child of the previous label in the branch:

/example.rpath.org@corp:devel//example.rpath.org@corp:1-devel

Conary often abbreviates the branch when displaying version strings, leaving out the common information between parent and shadow labels:

/example.rpath.com@corp:devel//1-devel

See the Branching Features section for more information about version strings of shadows.

Each label in the branch includes a branch name which is different from the branch. See the Branch Name section.

Label

The label portion of the version string includes the repository hostname and the branch name, separated by the @ symbol. System administrators use labels in Conary configuration, especially when identifying update paths (install label paths).

Repository Hostname

The repository hostname is the DNS hostname associated with the Conary repository. In rBuilder, this is usually in the format <projectname>.<rbuilder_domain>, such as in example.rpath.org where example is the string that identifies the rBuilder project and rpath.org is where rBuilder resides.

Branch Name

The branch name portion of a label identifies the branch among others in the same repository. The branch name includes a namespace and a tag separated by a colon (:).

Namespace

The namespace is a portion of a label typically used to identify a corporation, derivative distribution, or owner of the namespace. For example, rPath Linux uses rpl, and rPath products each use rpath.

rPath maintains a registry of namespace identifiers to avoid conflicts.

Tag

The tag is a portion of a label typically used to identify a development stage. In rPath's recommended release management strategy, development includes a versionless devel trunk, a <version>-<stage> format for versioned development, and the version alone for a production version.

Revision

The revision contains values that help determine which version of a trove is more recent than another. All troves include an upstream version string and a source count, and troves other than source components include a build count. These values are separated by dashes (-), and a single slash (/) separates the branch and revision in a version string.

Upstream Version String

The upstream version string, sometimes called the package version or group version, is an arbitrary value assigned by the package or group recipe in the version line. Developers typically use the version value of the software (in a package) or appliance (in a group).

Conary uses this value to compare whether two troves are the same version or different versions, but Conary does not determine whether a different version is older or newer. Conary determines older and newer versions of a trove by evaluating the source count and build count, which Conary automatically assigns and increments.

Source Count

The source count is a value that starts at 1 the first time the trove is saved (committed or checked in) to the repository, and it is incremented each time a change is committed. This portion corresponds to a release number in other packaging technologies.

If this number has a decimal (.), it is a shadow. The numbers represent two source counts:

• Number before the decimal: The source count of the last modification was merged from the parent branch
• Number after the decimal: The source count of the shadow

A 0 holds the place before the decimal if the version value changes and no changes have been merged from the parent. Multiple decimals represent a hierarchy of shadowing. See the Branching Features section for more information about version strings of shadows, including how revision numbers are incremented when shadowing and merging.

Build Count

The build count value starts at 1 when the trove is first built (cooked) in the repository, and it is incremented each time the trove is built.

Builds are done from source components (:source), so source components themselves do not carry a build counts. Use conary repquery on a package's source component to see its revision:

$> conary rq timescript:source=example.rpath.org@corp:devel --full-versions
timescript:source=/example.rpath.org@corp:devel/1.0-2
$> conary rq timescript=example.rpath.org@corp:devel --full-versions
timescript=/example.rpath.org@corp:devel/1.0-2-1

Branching Features

Developers use shadowing and cloning to create new development branches. A full version string of a shadow (or the clone of a shadow) has two distinguishing features:

• The branch includes two or more labels separated by double slashes, as described in the Branch section.
• The source count includes two or more numbers separated by decimals, as described in the Source Count section.

Branches in Shadows and Clones

Conary appends the parent branch with the shadow's label to create the branch of the shadow. The following are the branches of a parent trove, its shadow, and the shadow of a shadow:

/example.rpath.com@corp:devel
/example.rpath.com@corp:devel//example.rpath.com@corp:1-devel
/example.rpath.com@corp:devel//example.rpath.com@corp:1-devel//example.rpath.com@corp:1-devel-again

As previously mentioned in the Branch section, Conary often abbreviates the branch of a shadow by including only parts of the label that are different between parent and shadow. The following are a branch name of a shadow and an abbreviated form of the branch:

/example.rpath.org@corp:devel//example.rpath.org@corp:1-devel
/example.rpath.org@corp:devel//1-devel

Because cloning in Conary creates a sibling relationship between the original trove and its clone, Conary replaces the original trove's label with the sibling's label to create the branch of the clone. When cloning a shadow, this results in two branches that shadow the same parent. The following are the branches of a parent trove, its shadow, and a sibling (clone) of the shadow:

/example.rpath.com@corp:devel
/example.rpath.com@corp:devel//example.rpath.com@corp:1-devel
/example.rpath.com@corp:devel//example.rpath.com@corp:1-test

Revisions in Shadowing and Merging

The following example shows the change in a source component's revision after a shadow merges updates from a parent branch. A shadow is made from revision 1.5.0-2, and development proceeds on both the parent and shadow branches. Developers on the shadow merge changes from revision 1.5.0-6 on the parent branch to 1.5.0-2.1 on the shadow to create new shadow revision 1.5.0-6.1: