Dev:Versions: Difference between revisions

From railML 2 Wiki
Jump to navigation Jump to search
[unchecked revision][unchecked revision]
(Page added - first release)
 
(Content copied from Assemblas Wiki page "Versioning_Policy", some changes for better integration of both parts)
Line 1: Line 1:
== Recommendations on version numbers ==
== Release Policy ==


How to describe the version number of a RailML file? Or to find out which version a RailML file belongs to?
=== Major Release ===
 
; Reason : Commited changes have affects on XML-instance files and should be announced in advance in corresponding railML-newsgroups.
; Decision : Tagging a major release after railML conferences' consensus
; Version number : Increasing first digit, e.g. <code>version="2.0"</code>
; Namespace : Changing the year in the namespace string, e.g. <code>xmlns="<nowiki>http://www.railml.org/schemas/2009</nowiki>"</code>
 
=== Minor Release ===
 
; Reason : Commited changes have no affects on XML-instance files, but on other coordinators' XSD-schema files.<br>Commits of new elements, types and/or attributes are allowed.
; Decision : Tagging a minor release after railML coordinators' consensus
; Version number : Increasing second digit, e.g. <code>version="2.1"</code>
; Namespace : Up to now the year changed in the namespace string. Maybe this policy changes from railML 3.0 on the way it was originally intended: not changing the namespace string. e.g. <code>xmlns="<nowiki>http://www.railml.org/schemas/2011</nowiki>"</code>
 
=== Corrigendum ===
 
; Reason : Corrigendum commits and cosmetic changes with no affect on XML-instance files are allowed.
; Decision : Tagging a corrigendum after railML coordinators' consensus
; Version number : Increasing third digit, e.g. <code>version="2.0.1"</code>
; Namespace: No influence on the namespace string, e.g. <code>xmlns="<nowiki>http://www.railml.org/schemas/2009</nowiki>"</code>
 
=== Unofficial/Developers Version ===
 
; Reason : Depending on the current policy only Subversion commits for corrigendum, minor or major releases are checked into the repository for further feature development.
; Decision : User requirements from the forum are kept in the railML Trac tickets. The railML coordinators prioritize them, code each single topic in a railMLish way and commit changed files into the Subversion repository. See also [[CO:versioning|Officially released versus developer version]]
; Version number : Each atomic Subversion commit is tagged with the increasing Subversion number. The last official version number is expanded by the Subversion release number. e.g. <code>version="2.1r460"</code>
; Namespace : No influence on the namespace string, e.g. <code>xmlns="<nowiki>http://www.railml.org/schemas/2011</nowiki>"</code>
 
== Version numbers and corresponding namespaces ==
 
How to describe the version number of a railML file? Or to find out which version a railML file belongs to?


=== Version numbers ===
=== Version numbers ===


You will find a version attribute in the RailML root element {{CO:Tag|railml}} as well as in the root elements of the sub-schemas as {{IS:Tag|infrastructure}}, {{RS:Tag|rollingstock}}, {{TT:Tag|timetable}}, a. s. o.
You will find a {{Attr|version}} attribute in the railML root element {{CO:Tag|railml}} as well as in the root elements of the sub-schemas as {{IS:Tag|infrastructure}}, {{RS:Tag|rollingstock}}, {{TT:Tag|timetable}}. This attribute is to be used for the version number of the railML schema the XML file is based on.
 
Major, minor and corrigendum version are separated by a dot, the release number is separated by r. Corrigendum and release number are optional:
<blockquote>
<major version>'''.'''<minor version>['''.'''<corrigendum>]['''r'''<release number>]
</blockquote>
 
The following rules apply:
 
* The release number shall be omitted if a railML file is based on an "official released railML version". This applies to railML '''2.0r270''' and '''2.1r409''' which both shall be given as '''2.0''' respectively '''2.1''' without release number.
 
* The release number shall be considered mandatory in all other cases, e. g. if it is "an unofficial release version" but an intermediate. For more information on the relevance of intermediate versions see [[CO:versioning|Officially released versus developer version]].


This attribute is to be used for the version number of the RailML Schema the XML file is based on. This version number has the layout<br>
* The attribute {{Attr|version}} of the root element of the railML file shall be considered mandatory. If the root element of the railML file is {{CO:Tag|railml}}, the attribute {{Attr|version}} of the subsequent elements {{IS:Tag|infrastructure}}, {{RS:Tag|rollingstock}}, {{TT:Tag|timetable}} are optional. If they are used, they have to be identical to the {{Attr|version}} of {{CO:Tag|railml}}.
<majorVersion>'''.'''<minorVersion>['''r'''ReleaseNumber]<br>
e.g. '''2.0''', '''1.1r4''' or '''2.0r271'''. Major version and minor version are separated by a dot, the optional release number is separated by r. The following rules apply:
* The release number shall be omitted if a RailML file is based on an o'''fficial released RailML version'''. This applies to RailML 2.0r270 and 2.1r409 which both shall be given as 2.0 respectively 2.1 without release number.
* The release number shall be considered compulsory in all other cases, e. g. if it is '''not''' an official release version but an intermediate. For more information on the relevance of intermediate versions see [[CO:versioning|Officially released versus developer version]].
* The attribute {{Attr|version}} of the root element of the RailML file shall be considered compulsory. If the root element of the RailML file is {{CO:Tag|railml}}, the attribute {{Attr|version}} of the subsequent elements {{IS:Tag|infrastructure}}, {{RS:Tag|rollingstock}}, {{TT:Tag|timetable}}, a. s. o. are optional. If they are used, they have to be identical to the {{Attr|version}} of {{CO:Tag|railml}} - no differences are allowed.


If the actual Schema is based on an official RailML Schema but has own minor changes, it is recommended to leave {{Attr|version}} with the original RailML version number and to use {{CO:Doc|dc:format}} and/or {{CO:Doc|dc:identifier}} for an own version number which describes the minor changes. (See also the description of these elements.) However, it is a question of how far the “minor changes” lead away from the original RailML schema. Normally, if compatibility is rather improbable, it should not be declared as RailML anymore and therefore explicitly use a version number (and namespace!) which cannot be mixed with the original RailML versions.
* The corrigendum release number is mandatory, if the release is tagged this way. Otherwise it shall be ommited.


=== Common attributes depending on the RailML version ===
This official railML {{Attr|version}} number should not be confused with an implementation dependent software version in the metadata elements {{CO:Doc|dc:format}} and/or {{CO:Doc|dc:identifier}}.


Both common attributes {{Attr|xmlns}} and {{Attr|xsi:schemaLocation}} depend at least indirectly on the RailML version. There are similar rules for these “namespaces” as for the versions.
=== railML namespace declarations ===


The value of the railML namespace is defined by the railML initiative. A RailML file You have to use the namespace value which was released with the RailML version (as written in the XSD files). Not each RailML version needs to have an own namespace value. So some RailML versions may share the same namespace value. It is intended that each major version of RailML gets a new namespace value.
As above mentioned the XML namespace does also change with the railML version. The following table shows this relationship for all official railML versions.


For general information about namespaces see [[CO:catalog|Defining namespaces and validating railML files]].
{|style="text-align:center" cellspacing="5" cellpadding="5"
|-
! railML version number
! railML namespace string
! remote schema location
|-
| 1.0
| no namespace
| different schema locations for sub-schemas
|-
| 1.1
| <nowiki>http://www.railml.org/schemas/2007</nowiki>
| http://www.railml.org/schemas/2007/railML-1.1/railML.xsd
|-
| 2.0
| <nowiki>http://www.railml.org/schemas/2009</nowiki>
| http://www.railml.org/schemas/2009/railML-2.0/railML.xsd
|-
| 2.1
| <nowiki>http://www.railml.org/schemas/2011</nowiki>
| http://www.railml.org/schemas/2011/railML-2.1/railML.xsd
|}


* A RailML file based on an official released RailML version must contain the namespace of the official version. This is<br>
The XML file should declare the same XML namespace (identical string) as defined by its corresponding XML Schema. For general information about namespaces see [[CO:catalog|Defining namespaces and validating railML files]].
** for RailML 2.0: <nowiki>http://www.railml.org/schemas/2009</nowiki>
** for RailML 2.1: <nowiki>http://www.railml.org/schemas/2011</nowiki>
* A RailML file based on an intermediate release shall refer to the namespace of the '''previous''' (not the next) official version. This means, the last change from an intermediate release to a major version has to be the namespace value (and the version number, of course).


And, concerning web-based schema location:
A railML file based on an intermediate release with remote schema location shall refer to the Subversion repository of the release. This is
* A RailML file based on an official released RailML with web-based schema location shall refer to the “railML.xsd” following the format <namespace>'''/railML-'''<version>'''/railML.xsd''', e. g.
<blockquote>
** for RailML 2.0: <nowiki>http://www.railml.org/schemas/2009/railML-2.0/railML.xsd</nowiki>
'''<nowiki>http://trac.assembla.com/railML/export/</nowiki>'''<release number>'''<nowiki>/trunk/schema/railML.xsd</nowiki>'''
** for RailML 2.1: <nowiki>http://www.railml.org/schemas/2011/railML-2.1/railML.xsd</nowiki>
</blockquote>
* A RailML file based on an intermediate release with web-based schema location shall refer to the Subversion repository of the release. This is '''<nowiki>http://trac.assembla.com/railML/export/</nowiki>'''<releaseNo>'''<nowiki>/trunk/schema/railML.xsd</nowiki>'''.


=== Examples ===
== Examples ==


RailML file of official released RailML version 2.0, web-based schema location:  
railML file of official released railML version 2.0, remote schema location:  


<pre>
<syntaxhighlight line lang="xml">
<?xml version="1.0" encoding="UTF-8"?>
<?xml version="1.0" encoding="UTF-8"?>
<railml version="2.0"
<railml version="2.0"
   xmlns="http://www.railml.org/schemas/2009"  
   xmlns="http://www.railml.org/schemas/2009"
  xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"  
   xsi:schemaLocation="http://www.railml.org/schemas/2009 http://www.railml.org/schemas/2009/railML-2.0/railML.xsd">
   xsi:schemaLocation="http://www.railml.org/schemas/2009 http://www.railml.org/schemas/2009/railML-2.0/railML.xsd">
   ...
   ...
</railml>
</railml>
</pre>
</syntaxhighlight>


RailML file of intermediate release #416 (between official releases 2.1 and 2.2) , web-based schema location:
railML file of intermediate release #416 (between official releases 2.1 and 2.2) , remote schema location:


<pre>
<syntaxhighlight line lang="xml">
<?xml version="1.0" encoding="UTF-8"?>
<?xml version="1.0" encoding="UTF-8"?>
<railml version="2.1r416"
<railml version="2.1r416"
   xmlns="http://www.railml.org/schemas/2011"  
   xmlns="http://www.railml.org/schemas/2011"
  xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
   xsi:schemaLocation="http://www.railml.org/schemas/2011 http://trac.assembla.com/railML/export/416/trunk/schema/railML.xsd">
   xsi:schemaLocation="http://www.railml.org/schemas/2011 http://trac.assembla.com/railML/export/416/trunk/schema/railML.xsd">
   ...
   ...
</railml>
</railml>
</pre>
</syntaxhighlight>

Revision as of 17:06, 16 October 2012

Release Policy

Major Release

Reason
Commited changes have affects on XML-instance files and should be announced in advance in corresponding railML-newsgroups.
Decision
Tagging a major release after railML conferences' consensus
Version number
Increasing first digit, e.g. version="2.0"
Namespace
Changing the year in the namespace string, e.g. xmlns="http://www.railml.org/schemas/2009"

Minor Release

Reason
Commited changes have no affects on XML-instance files, but on other coordinators' XSD-schema files.
Commits of new elements, types and/or attributes are allowed.
Decision
Tagging a minor release after railML coordinators' consensus
Version number
Increasing second digit, e.g. version="2.1"
Namespace
Up to now the year changed in the namespace string. Maybe this policy changes from railML 3.0 on the way it was originally intended: not changing the namespace string. e.g. xmlns="http://www.railml.org/schemas/2011"

Corrigendum

Reason
Corrigendum commits and cosmetic changes with no affect on XML-instance files are allowed.
Decision
Tagging a corrigendum after railML coordinators' consensus
Version number
Increasing third digit, e.g. version="2.0.1"
Namespace
No influence on the namespace string, e.g. xmlns="http://www.railml.org/schemas/2009"

Unofficial/Developers Version

Reason
Depending on the current policy only Subversion commits for corrigendum, minor or major releases are checked into the repository for further feature development.
Decision
User requirements from the forum are kept in the railML Trac tickets. The railML coordinators prioritize them, code each single topic in a railMLish way and commit changed files into the Subversion repository. See also Officially released versus developer version
Version number
Each atomic Subversion commit is tagged with the increasing Subversion number. The last official version number is expanded by the Subversion release number. e.g. version="2.1r460"
Namespace
No influence on the namespace string, e.g. xmlns="http://www.railml.org/schemas/2011"

Version numbers and corresponding namespaces

How to describe the version number of a railML file? Or to find out which version a railML file belongs to?

Version numbers

You will find a version attribute in the railML root element <railml> as well as in the root elements of the sub-schemas as <infrastructure>, <rollingstock>, <timetable>. This attribute is to be used for the version number of the railML schema the XML file is based on.

Major, minor and corrigendum version are separated by a dot, the release number is separated by r. Corrigendum and release number are optional:

<major version>.<minor version>[.<corrigendum>][r<release number>]

The following rules apply:

  • The release number shall be omitted if a railML file is based on an "official released railML version". This applies to railML 2.0r270 and 2.1r409 which both shall be given as 2.0 respectively 2.1 without release number.
  • The release number shall be considered mandatory in all other cases, e. g. if it is "an unofficial release version" but an intermediate. For more information on the relevance of intermediate versions see Officially released versus developer version.
  • The attribute version of the root element of the railML file shall be considered mandatory. If the root element of the railML file is <railml>, the attribute version of the subsequent elements <infrastructure>, <rollingstock>, <timetable> are optional. If they are used, they have to be identical to the version of <railml>.
  • The corrigendum release number is mandatory, if the release is tagged this way. Otherwise it shall be ommited.

This official railML version number should not be confused with an implementation dependent software version in the metadata elements dc:format and/or dc:identifier.

railML namespace declarations

As above mentioned the XML namespace does also change with the railML version. The following table shows this relationship for all official railML versions.

railML version number railML namespace string remote schema location
1.0 no namespace different schema locations for sub-schemas
1.1 http://www.railml.org/schemas/2007 http://www.railml.org/schemas/2007/railML-1.1/railML.xsd
2.0 http://www.railml.org/schemas/2009 http://www.railml.org/schemas/2009/railML-2.0/railML.xsd
2.1 http://www.railml.org/schemas/2011 http://www.railml.org/schemas/2011/railML-2.1/railML.xsd

The XML file should declare the same XML namespace (identical string) as defined by its corresponding XML Schema. For general information about namespaces see Defining namespaces and validating railML files.

A railML file based on an intermediate release with remote schema location shall refer to the Subversion repository of the release. This is

http://trac.assembla.com/railML/export/<release number>/trunk/schema/railML.xsd

Examples

railML file of official released railML version 2.0, remote schema location: 

<?xml version="1.0" encoding="UTF-8"?>
<railml version="2.0"
  xmlns="http://www.railml.org/schemas/2009"
  xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" 
  xsi:schemaLocation="http://www.railml.org/schemas/2009 http://www.railml.org/schemas/2009/railML-2.0/railML.xsd">
  ...
</railml>

railML file of intermediate release #416 (between official releases 2.1 and 2.2) , remote schema location: 

<?xml version="1.0" encoding="UTF-8"?>
<railml version="2.1r416"
  xmlns="http://www.railml.org/schemas/2011"
  xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
  xsi:schemaLocation="http://www.railml.org/schemas/2011 http://trac.assembla.com/railML/export/416/trunk/schema/railML.xsd">
  ...
</railml>
Retrieved from "https://wiki2.railml.org/index.php?title=Dev:Versions&oldid=3269"