Permalink
Switch branches/tags
Nothing to show
Find file Copy path
Fetching contributors…
Cannot retrieve contributors at this time
95 lines (79 sloc) 3.46 KB
---
# Copyright 2017 Yahoo Holdings. Licensed under the terms of the Apache 2.0 license. See LICENSE in the project root.
title: "Versioning in the Container"
---
<p>
Code component as well as many other artifacts in the container can be versioned.
This document explains the format and semantics of these versions and how they are referred.
</p>
<h2 id="format">Format</h2>
<p>
Versions are on the form
<pre>
version ::= major [ "." minor [ "." micro [ "." qualifier ]]]
</pre>
Where <code>major</code>, <code>minor</code>, and <code>micro</code>
are integers and <code>qualifier</code> is any string.
</p><p>
A version is appended to an id separated by a colon.
In cases where a file is created for each component version,
the colon is replaced by a dash in the file name.
</p>
<h2 id="ordering">Ordering</h2>
<p>
Versions are ordered first by major, then minor, then micro and then
by doing a lexical ordering on the qualifier.
This means that <code>a:1 &lt; a:1.0 &lt; a:1.0.0 &lt; a:1.1 &lt; a:1.1.0 &lt; a:2</code>
</p>
<h2 id="referencing-a-versioned-component">Referencing a versioned Component</h2>
<p>
Whenever component is referenced by id (in code or configuration),
a fully or partially specified version may be included in the reference
by using the form <code>id:versionSpecification</code>.
Such references are resolved using the following rules:
<ul>
<li>An id without any version specification resolves to the highest
version not having a qualifier</li>
<li>A partially or full version specification resolves to the highest
version not having a qualifier which matches the specification.</li>
<li>Versions with qualifiers are matched only by exact match.</li>
</ul>
Example: Given a component with id <code>a</code> having these
versions: <code>[1.1, 1.2, 1.2, 1.3.test, 2.0]</code>
<ul>
<li>The reference <code>a</code> will resolve to <code>a:2.0</code></li>
<li>The reference <code>a:1</code> will resolve to <code>a:1.2</code></li>
<li>The only way to resolve to the "test" qualified version
is by using the exact reference <code>a:1.3.test</code></li>
<li>These references will not resolve: <code>a:1.3</code>, <code>a:3</code>, <code>1.2.3</code></li>
</ul>
</p>
<h2 id="merging-specifications-for-chained-components">Merging specifications for chained Components</h2>
<p>
In some cases, there is a need for merging multiple references into one.
An example is inheritance of chains of version references,
where multiple inherited chains may reference the same component.
</p><p>
Two version references are said to be <em>compatible</em> if one is a prefix of the other.
In this case the most specific version is used.
If they are not compatible they are <em>conflicting</em>. Example:
<pre>
&lt;search&gt;
&lt;searcher id="Searcher:2.3" class="com.yahoo.search.example.Searcher"/&gt;
&lt;searcher id="Searcher:2.4" class="com.yahoo.search.example.Searcher"/&gt;
&lt;chain id="parenta"&gt;
&lt;searcher id="Searcher:2"&gt;&lt;/searcher&gt;
&lt;/chain&gt;
&lt;chain id="parentb"&gt;
&lt;searcher id="Searcher:2.3"&gt;&lt;/searcher&gt;
&lt;/chain&gt;
&lt;chain id="parentc"&gt;
&lt;searcher id="Searcher:2.4"&gt;&lt;/searcher&gt;
&lt;/chain&gt;
&lt;!-- This chain will get Searcher:2.3 --&gt;
&lt;chain id="childa" inherits="parenta parentb" /&gt;
&lt;!-- Error, as Searcher:2.3 and Searcher:2.4 are conflicting --&gt;
&lt;chain id="childb" inherits="parentb parentc" /&gt;
&lt;/search&gt;
</pre>
</p>