Dev:Versions: Difference between revisions

From railML 2 Wiki
Jump to navigation Jump to search
[checked revision][checked revision]
(Abgrenzung)
({{mirror}})
Line 1: Line 1:
{{navi}}{{note|The subject of this article are official version releases. If you are interested in accessing, setting and naming developer versions, see [[dev:versioning]].}}
{{mirror}}
== 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. <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 railML 2.x the year changed in the namespace string. This policy will be changed from railML 3.1 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 {{rml}} releases are checked into the repository for further feature development.
; Decision : User requirements from the forum are kept in the {{rml}} Trac tickets. The railML coordinators prioritize them, code each single topic in a {{rml}}ish way and commit changed files into the Subversion repository. See also [[CO:versioning|Officially released versus developer version]] for more information.
; 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 {{rml}} file? Or to find out which version a {{rml}} file belongs to?
 
=== Version numbers ===
 
You will find a {{Attr|version}} attribute in the {{rml}} 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 {{rml}} 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 is required to be omitted if a {{rml}} file is based on an '''official released {{rml}} version'''. This applies to {{rml}}'s release numbers
  * '''2.0r270''' has to be given as '''2.0''',
  * '''2.1r409''' has to be given as '''2.1''',
  * '''2.2r602''' has to be given as '''2.2''',
  * '''2.4r668''' has to be given as '''2.3''',
  * '''2.4r862''' has to be given as '''2.4''' and
  * '''3.1r989''' has to be given as '''3.1''', all respectively 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]].
 
* The attribute {{Attr|version}} of the root element of the {{rml}} file shall be considered mandatory. If the root element of the {{rml}} 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}}.
 
* The corrigendum release number is mandatory, if the release is tagged this way. Otherwise it shall be ommited.
 
This official {{rml}} {{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}}.
 
=== {{rml}} 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.
 
<!--{|style="border: 1pt black solid" cellspacing="5" cellpadding="5" style="background:#EAECF0-->
{|class="wikitable sortable"
|-
! railML version number
! railML namespace string
! remote schema location
! HTTPS access
|-
| 1.0
| no namespace
| different schema locations for sub-schemas
| no
|-
| 1.1
| <nowiki>http://www.railml.org/schemas/2007</nowiki>
| http://www.railml.org/schemas/2007/railML-1.1/railML.xsd
| no
|-
| 2.0
| <nowiki>http://www.railml.org/schemas/2009</nowiki>
| http://www.railml.org/schemas/2009/railML-2.0/railML.xsd
| yes, optional
|-
| 2.1
| <nowiki>http://www.railml.org/schemas/2011</nowiki>
| http://www.railml.org/schemas/2011/railML-2.1/railML.xsd
| yes, optional
|-
| 2.2
| <nowiki>http://www.railml.org/schemas/2013</nowiki>
| http://www.railml.org/schemas/2013/railML-2.2/railML.xsd
| yes, optional
|-
| 2.3
| <nowiki>http://www.railml.org/schemas/2016</nowiki>
| http://www.railml.org/schemas/2016/railML-2.3/schema/railML.xsd
| yes, optional
|-
| 2.4
| <nowiki>https://www.railml.org/schemas/2018</nowiki>
| https://www.railml.org/schemas/2018/railML-2.4/schema/railML.xsd
| yes, mandatory
|-
| 3.0 (alpha & beta only)
| <nowiki>http://www.railml.org/schemas/2015</nowiki>
| ''Alpha & Beta phases finished''
| no
|-
| 3.1
| <nowiki>https://www.railml.org/schemas/3.1</nowiki>
| https://www.railml.org/schemas/3.1/railml3.xsd
| yes, mandatory
|}
 
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]].
 
A {{rml}} file based on an intermediate release with remote schema location shall refer to the Subversion repository of the release. This is
<blockquote>
'''<nowiki>http://trac.railml.org/browser/railML/trunk/schema/railML.xsd?rev=</nowiki>'''<release number>'''
</blockquote>
 
== Examples ==
 
railML file of official released railML version 2.0, remote schema location:
 
<syntaxhighlight line lang="xml">
<?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>
</syntaxhighlight>
 
railML file of intermediate release #416 (between official releases 2.1 and 2.2) , remote schema location:
 
<syntaxhighlight line lang="xml">
<?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.railml.org/browser/railML/trunk/schema/railML.xsd?rev=416">
  ...
</railml>
</syntaxhighlight>
 
[[Category:GeneralDescription]]
[[category:Common Concept]]

Revision as of 17:53, 24 January 2020

🗒️ This page is mirrored from page Dev:Versions in The railML® 3 wiki.
RailML Trademark RGB V2.png
XML Railway exchange format
https://railML.org
Latest release: 2.5
(September 1st, 2021)
 
Main Menu
 
Subschemas
XML tree
UML diagrams
Use cases
Versions & Changes
railML® 3 Wiki – RailTopoModel® Wiki
🗒️ The subject of this article are official version releases. If you are interested in accessing, setting and naming developer versions, see dev:versioning.

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="https://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 railML® 2.x the year and version changed in the namespace string. From railML® 3.1 onward the year is no longer part of the namespace string. In consequence the version is changed with each minor version, e.g. xmlns="https://www.railml.org/schemas/3.2".

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="https://www.railml.org/schemas/2009"

Unofficial/Developers Version

Reason
Depending on the current policy only Subversion commits for corrigendum, minor or major railML® releases are checked into the repository for further feature development.
Decision
User requirements from the forum are kept in the railML® ticket system: For railML® 2 they can be found here; for railML® 3 they can be found here. The railML® coordinators prioritize them, code each single topic in a railML®ish way and commit changed files into the Subversion repository. See also Officially released versus developer version for more information.
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="https://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 is required to be omitted if a railML® file is based on an official released railML® version. This applies to railML®'s release numbers
 * 2.0r270 has to be given as 2.0,
 * 2.1r409 has to be given as 2.1,
 * 2.2r602 has to be given as 2.2,
 * 2.3r668 has to be given as 2.3,
 * 2.4r862 has to be given as 2.4,
 * 2.5r1327 has to be given as 2.5 and
 * 3.1r989 has to be given as 3.1, all respectively without release number.
 * Since 3.2 there is no usage on SVN anymore as railML.org switched to Gitlab and therefore no more 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.

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 HTTPS access
1.0 no namespace different schema locations for sub-schemas no
1.1 http://www.railml.org/schemas/2007 https://schemas.railml.org/2007/railML-1.1/railML.xsd no
2.0 http://www.railml.org/schemas/2009 https://schemas.railml.org/2009/railML-2.0/railML.xsd yes, optional
2.1 http://www.railml.org/schemas/2011 https://schemas.railml.org/2011/railML-2.1/railML.xsd yes, optional
2.2 http://www.railml.org/schemas/2013 https://schemas.railml.org/2013/railML-2.2/railML.xsd yes, optional
2.3 http://www.railml.org/schemas/2016 https://schemas.railml.org/2016/railML-2.3/schema/railML.xsd yes, optional
2.4 https://www.railml.org/schemas/2018 https://schemas.railml.org/2018/railML-2.4/schema/railML.xsd yes, mandatory
2.5 https://www.railml.org/schemas/2021 https://schemas.railml.org/2021/railML-2.5/schema/railML.xsd yes, mandatory
3.0 (alpha & beta only) https://www.railml.org/schemas/2015 Alpha & Beta phases finished no
3.1 https://www.railml.org/schemas/3.1 https://schemas.railml.org/3.1/railml3.xsd yes, mandatory
3.2 https://www.railml.org/schemas/3.2 https://schemas.railml.org/3.2/railml3.xsd yes, mandatory

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 a commit on our development platform (link to the railML® website). This is

  • for railML® 2: https://development.railml.org/railml/version2/-/commit/<commit hash>
  • for railML® 3: https://development.railml.org/railml/version3/-/commit/<commit hash>

For instance commit 5f735749 (railML® 2) can be found under https://development.railml.org/railml/version2/-/commit/5f735749. It corresponds to commit [416] of our legacy Apache Subversion Control (Wiki banner.png) (SVN).
Commit 6e7d61fa (railML® 3) can be found under https://development.railml.org/railml/version3/-/commit/6e7d61fa and corresponds to SVN commit [1026].

Licenses

All currently supported railML® versions are licensed dually under a restricted form of the Creative Commons licence (external link) CC-BY-NC-ND and (for certified programmes) in a commercial licence. To learn more about the licence terms see https://www.railml.org/en/user/licence.html (link to the railML® website).

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="https://www.railml.org/schemas/2009"
  xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" 
  xsi:schemaLocation="https://www.railml.org/schemas/2009 https://schemas.railml.org/2009/railML-2.0/railML.xsd">
  ...
</railml>

railML® file of intermediate release SVN #416/commit [5f735749] (between official releases 2.1 and 2.2), remote schema location: 

<?xml version="1.0" encoding="UTF-8"?>
<railml version="2.1r416"
  xmlns="https://www.railml.org/schemas/2011"
  xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
  xsi:schemaLocation="https://development.railml.org/railml/version2/-/raw/5f73574937776c5fc7b228d7eb149c64f96b2a34/schema/railML.xsd">
  ...
</railml>
Retrieved from "https://wiki2.railml.org/index.php?title=Dev:Versions&oldid=10436"