SVX : Software Versioning in XML

the past, present and future of a file

Abstract - top

This document is a presentation of the SVX format definition and how to use it. SVX is short for Software Versioning in XML. It describes a language, based on XML, to describe different versions of a software, part of a software or any other thing subject to version increments.

Author : Steve Lhomme <steve dot lhomme at free dot fr> (replace the "at" and "dot" by the real ones... I don't want any spam)

Organisation : MUKOLI <http://mukoli.free.fr/>

Requirements - top

To understand SVX you need to know about XML, DTD and also how versions of a product can be handled. Here are few explanations if you don't know about these :

  • XML is becoming more and more popular in both the corporate world and non lucrative organisations. If you want to know more about XML, you can browse xml.com or the WWW Consortium which is responsible for making XML a standard.
  • DTD is part of the SGML specification which is the parent of XML and HTML. It is the first language that was used to describe/define the tags and attributes in XML or HTML. Now it is being superceded by Schema (which describes XML in XML, but still relies on DTD) and Relax, but SVX is currently only described in a form of a DTD.
    I found this little tutorial on DTD which is simple and efficient.
  • Versioning : as you probably have noticed everything in the industrial world now has a version number. From the software you're using (the first basic use of SVX) to cars, documents, etc.
    The idea behind the version number is that with this number the user can get meta informations like : when it was manufactured, is it the latest version, what this version lacks compared to newer ones, are newer ones compatible with the current one, etc.

History - top

Although SVX is very new, it doesn't start from scratch. I wanted to be able to update a software (out_lame) automatically in a nice way. So I searched the web for Open/Free implementations of this feature and didn't find nearly anything. I wanted something based on XML, that could be as portable as possible. And I only found XSA and the Microsoft OSD formats.

XSA was the best solution, but was only created to describe the current software version and not other versions, and the differences between these versions.

MS-OSD is just a format to describe software that can be updated in a browser, not in the general (and bigger) software world.

So I decided that I had to create my own new format, based on XSA. And that's how SVX was created and grown quickly, by adding (or changing) what I needed to SVX.

The current version of SVX is still subject to changes, but the core is already done and stable. It's finally quite different from XSA, but switching from both formats should be easy (with a translating software).

Example A - top

This example describe the minimal requirements any SVX description file should include. You can also get the source file.

  <?xml version="1.0" encoding="UTF-8" ?>
  <!DOCTYPE svx SYSTEM "http://mukoli.free.fr/svx/svx.dtd">
- <svx version="1.0">
  </svx>
  

Explanations

This is the minimum requirements to have a valid baisc SVX file.

  • <?xml version="1.0" encoding="UTF-8" ?>

    The first line is the tag that says the document is an XML document encoded with the UTF-8 character set (8 bits Unicode). It's a line common to most XML files.
  • <!DOCTYPE svx SYSTEM "http://mukoli.free.fr/svx/svx.dtd">

    The second line defines that all the tags inside the svx one are to be understood as relying on the svx.dtd located at http://mukoli.free.fr/svx/svx.dtd (which is the official place for this DTD).
  • <svx version="1.0">
    </svx>

    The two remaining lines are the content of the SVX description. For this simple example there is no content. The only possible version number at the moment is 1.0.

Example B - top

This example is a basic example of a product description with only 1 version and 2 different packages for this version. You can also get the source file.

  <?xml version="1.0" encoding="UTF-8" ?>
  <!DOCTYPE svx SYSTEM "http://mukoli.free.fr/svx/svx.dtd">
- <svx version="1.0">
-   <product id="product-a">
-     <name>
        <text>my product A</text>
      </name>
-     <version name="1.0.0" date="2001-09-09">
-       <package type="binary">
          <text>this binary is not really on any mirror</text>
          <mirror href="about:null" country="fr" />
          <mirror href="about:null" country="en-uk" />
        </package>
-       <package type="source">
          <text>this source package is not really on any mirror</text>
          <mirror href="about:null" />
        </package>
-       <notes>
          <text lang="en">this is the inital version</text>
          <text lang="fr">la premiere version</text>
        </notes>
      </version>
    </product>
  </svx>
  

Explanations

This example is the same as the previous one, but this time there is some SVX content

  •   <product id="product-a">

    The product described here is labeled "product-a". This ID is a unique identifier that will be used to describe the same product, even across many SVX file. A SVX document can contain from 0 to many product description. It can also be updated using a remote address.
  • This product contains a name and only one version. A product can contain only one name tag, 0 to many licenses (some products have more than one license), and many versions.
  •     <name>
          <text>my product A that saves your life</text>
        </name>

    The name tag is just a 'global' tag for 1 or more text tags. Each text tag is a name and can have a different language. If more than one language is specified, only the first one is applied for this language.
  • In this case the human-readable name of the product is in english and is called "my product A that saves your life". When the language is not specified, the default value is english.
  •     <version name="1.0.0" date="2001-09-13">

    The version is the most important part of SVX. It contains all the informations corresponding to one stamped version. It can also be a future version of the software/product item. It can be composed of a license, packages, a dependency list, a note and a list of changes.
  • In this case the version of "product-a" is composed of 2 packages and a note about this version. It's named "1.0.0" which is a unique name to identify the version between other ones. It can be any ASCII text. The date of the version is also specified : 13 september 2001. The date is specified according to the ISO 8601 format. It can also contain the time.
  •       <download type="binary">

          <download type="source">

    The package 2 packages have different types, the first one is a binary version of "product-a" and the second one is a source version.
  •         <text>this binary is not really on any mirror</text>
            <mirror href="about:null" country="fr" />
            <mirror href="about:null" country="en-uk" />

    Each package can contain a verification list (used to make sure the package we donwload is correct), some activation items (not used for the moment), some text describing the package in a human-readable way and a list of mirrors to download the package.
  • In this example we only have a text (default in english) to describe each package and a few list of mirrors with NULL URLs (this is just an example).
  • Each mirror contain a URL and an optional country code (used to locate the nearest mirror).
  •       <notes>
            <text lang="en">this is the inital version</text>
            <text lang="fr">la premiere version</text>
          </notes>

    The note list following the packages is a general description of the specified version. It's composed of text items in different languages (english and french in this case).

Example C - top

You can also get the source file.

  <?xml version="1.0" encoding="UTF-8" ?>
  <!DOCTYPE svx SYSTEM "http://mukoli.free.fr/svx/svx.dtd">
- <svx version="1.0">
-   <product id="product-a">
-     <name>
        <text>my product A</text>
      </name>
-     <license type="free-software" name="BXAPL" href="http://www.bixoft.nl/english/license.htm">
      <!-- no text, get it on the URL -->
      </license>
-     <version name="1.0.1" date="2001-10-10" previous="1.0.0">
-       <package type="binary" lang="fr">
          <text lang="fr">nouvelle version qui supporte l'update par SVX</text>
          <text lang="en">new version that supports updates using SVX</text>
        </package>
-       <changes>
-         <bugfix id="17A2">
            <text>The date was not handled correctly</text>
          </bugfix>
-         <feature>
            <text>Added support for SVX updates.</text>
          </feature>
        </changes>
      </version>
-     <version name="1.0.0" date="2001-09-27">
-       <package type="binary">
          <text>this binary is not really on any mirror</text>
          <mirror href="about:null" country="fr" />
          <mirror href="about:null" country="en-uk" />
        </package>
-       <package type="source">
          <text>this source package is not really on any mirror</text>
          <mirror href="about:null" />
        </package>
-       <notes>
          <text lang="en">this is the inital version</text>
          <text lang="fr">la premiere version</text>
        </notes>
      </version>
    </product>
  </svx>
  

Explanations

This example is the same as example B, but this time with 2 versions of the same product. There is also an additional license tag.

  •     <license type="free-software" name="BXAPL" href="http://www.bixoft.nl/english/license.htm">

    This is the license that apply to that product. It applies to all version of the product, unless a license tag is added to the versions (that does not use the same license). In this case, the license is the BXAPL (it could be the GPL, BSD or anything else) and you can find the complete license text/info at the specified URL : http://www.bixoft.nl/english/license.htm. There could be the text of the license in many languages, but in this example it's not used.

    The type of license is mostly there for filtering (at the SVX parsing level). There can be as many licenses as you wish for the same products because of dual-licensing or cross-licensing possibilites (for example Qt is both covered by the QPL and the GPL).

  •     <version name="1.0.1" date="2001-10-10" previous="1.0.0">

        <version name="1.0.0" date="2001-09-27">

    These are the 2 different versions. The second (older) one is the same as example B and is unchanged. Consecutive versions of a product can be traced with the previous attribute or the dates of version (if previous is not found). This previous attribute must be a known version. In this example, the previous version of "1.0.1" is "1.0.0". There could be 2 versions that have the same previous; that would define 2 different branches.
  •       <package type="binary" lang="fr">

    This is the package for this new version. The differences with previous packages is that this one is for lang="fr" that means for french speaking systems.
  •       <changes>
          </changes>

    This is the newly introduced tag. It's one of the most important feature of SVX : the ability to trace introduced changes between consecutive versions. All the changes are text describing what happened between the previous version and the specified version.
  •         <bugfix id="17A2">
              <text>The date was not handled correctly</text>
            </bugfix>

    This first part is the bugfix list (in this case only 1 element in the list). It describes the bug fixed in this version (that existed in the previous version). The id is there to have a link between a bug database and the distributed version. There can also be a priority on the bug item. It's usefull to keep track of bugs not corrected and placed in a future version of the product. (yes ! SVX can describe future versions)
  •         <feature>
              <text>Added support for SVX updates.</text>
            </feature>

    This is the second list of changes (1 element again). It describes new features introduced in the specified versions. As for bugs, there can be a priority on the feature.

    There can be another type of changes, a list of improvements. An improvement is neither a bugfix nor a new feature. It's a feature that already existed but has been improved (a bug is only when there is a problem).

Example D - top

You can also get the source file.

  <?xml version="1.0" encoding="UTF-8" ?>
  <!DOCTYPE svx SYSTEM "http://mukoli.free.fr/svx/svx.dtd">
- <svx version="1.0">
-   <product id="french-UI" href="http://mukoli.free.fr/french-UI.svx" ihref="http://mukoli.free.fr/french-UI.html">
-     <name>
        <text>A french GUI for product A</text>
        <text lang="fr">Une interface en francais pour le produit A</text>
      </name>
      <license type="free-software" name="BXAPL" href="http://www.bixoft.nl/english/license.htm"/>
-     <version type="alpha" name="0.1.0" date="2001-10-22">
-       <dependency id="product-a" link="mandatory">
          <dversion name="1.0.1" compatible="true"/>
          <dversion name="1.0.0" compatible="false"/>
        </dependency>
      </version>
    </product>
-   <product id="product-a">
-     <name>
        <text>my product A</text>
      </name>
-     <license type="free-software" name="BXAPL" href="http://www.bixoft.nl/english/license.htm">
      <!-- no text, get it on the URL -->
      </license>
-     <version name="1.0.1" date="2001-10-10" previous="1.0.0">
-       <package type="binary" lang="fr">
          <text lang="fr">nouvelle version qui supporte l'update par SVX</text>
          <text lang="en">new version that supports updates using SVX</text>
        </package>
-       <changes>
-         <bugfix id="17A2">
            <text>The date was not handled correctly</text>
          </bugfix>
-         <feature>
            <text>Added support for SVX updates.</text>
          </feature>
        </changes>
      </version>
-     <version name="1.0.0" date="2001-09-27">
-       <package type="binary">
          <text>this binary is not really on any mirror</text>
          <mirror href="about:null" country="fr" />
          <mirror href="about:null" country="en-uk" />
        </package>
-       <package type="source">
          <text>this source package is not really on any mirror</text>
          <mirror href="about:null" />
        </package>
-       <notes>
          <text lang="en">this is the inital version</text>
          <text lang="fr">la premiere version</text>
        </notes>
      </version>
    </product>
  </svx>
  

Explanations

This example is the same as example C, but with a new product that depends on the "product-a".

  •   <product id="french-UI" href="http://mukoli.free.fr/french-UI.svx" ihref="http://mukoli.free.fr/french-UI.html">

    This is the new product specified. The name of the product is "french-GUI", http://mukoli.free.fr/french-UI.svx is the URL where you can get updated SVX informations on this product and http://mukoli.free.fr/french-UI.html is the place to get more informations on this product. The SVX update can contain informations on new and future (todo) versions of this product. The new information retreived can be replaced/merged in the current SVX file.

  •     <name>
          <text>A french GUI for product A</text>
          <text lang="fr">Une interface en francais pour le produit A</text>
        </name>

    As seen previously it's the name of the product. In this case there is an english text (default is always english) and a french text (usefull as this is a product for french speaking people).

  •     <version type="alpha" name="0.1.0" date="2001-10-22">

    This is the version of the product. It's an alpha-stage version (before beta and retail) that was released on the 22 October 2001 and the version name is 0.1.0. The type can be alpha, beta, retail and todo. A todo version is a version that doesn't exist yet and is planned to be released on the specified date with the speciefed corrections and improvements. This is how SVX can be used to describe the future.

  •       <dependency id="product-a" link="mandatory">

    This is a new tag. It specifies dependency of this product over other know products (products specified in the same file or included with a URL). In this case there is a depency only with one product which is "product-a". And this dependency is mandatory, which means you can't use "french-GUI" if "product-a" is not installed. The other dependencies types are exclusive (you can't have both product installed/working at the same tile) and optional (you can have both product installed but it's not mandatory).

    There can also be a priority number on depency to help resolve conflicts between dependencies. For ex : A depends on B but B is exclusive with A... The rule used will be the one with the bigger priority.

  •         <dversion name="1.0.1" compatible="true"/>
            <dversion name="1.0.0" compatible="false"/>

    The dversion tag specify the compatibility between the version of "french-GUI" and "product-a". In this case version 0.1.0 of "french-GUI" is compatible with version 1.0.1 of "product-a" but not with version 1.0.0.

Appendix A : the complete DTD - top

You can download the official one from http://mukoli.free.fr/svx/svx.dtd.

You can also check this HTML version generated with the Scite Editor

abstract

requirements

history

example A

example B

example C

example D

the DTD

 

Valid XHTML 1.0!