Handling minor changes within versions

by Joyce Dillon (railML.org) (comments: 0)

Throughout development of any program, plan or project, there are always new ideas or proposals that arise during the process. This prompts changes to be made or, in the case of railML ®, new minor and, eventually, major versions to be released. Simple extensions are not a problem, but mistakes pop up or opportunities to improve a certain aspect become available. After many years of experience with railML 2 and lots of feedback from our users, our coordinators are faced with the question: How should changes within minor versions be handled going forward?

What this is about…

First and foremost, what minor and major versions (or releases) are should be clarified. A new major version (e.g. railML 2 and railML 3) contains changes in principles or modelling rules that affect XML and are always announced well in advanced. On the other hand, a minor version’s changes keep basic ideas and principles and offer users of the previous version a simple upgrade. Here, new elements, types or attributes may also be added. Please refer to our "Dev:versions" wiki article for a more detailed description and further information.

When the development of railML 3 began, it was dedicated to a completely new Infrastructure model and the discussion on how to handle changes became relevant, as a new major release provided a fresh start and the opportunity to improve. In railML 2, the focus was set on compatibility between minor versions and this provided many advantages. However, it also led to some difficulties. To showcase the most blatant case, here is an example that will be known to long-time users of railML. There was a spelling mistake in the element <brigde> made in railML 2.0, which was kept instead of correcting it to <bridge> and can still be found in railML 2.5.

With this said, even though it increases compatibility, it also means that the mistake (or outdated element) must be kept throughout the entire major version, only being able to be removed when a new major version is released. For this reason, the decision needs to be made whether railML 3 will follow the same approach or try something new for more flexibility and better understanding.

Which versions will be affected?

With railML 3 as a new major version, the chance (and will) to try out something new presented itself. Therefore, this would be the only version (from the ones released so far) that might be affected by the possible changes. These options of how to continue will be discussed below.

The policy for railML 2 will remain as is, with new elements and attributes being added, but no elements or attributes being renamed or removed, only deprecated, further guaranteeing the downward compatibility.

What options do we have?

During our coordination meetings, comprehensive discussions have taken place and our coordinators have come up with the proposals listed below for railML 3. In any case, the changes between minor releases will be announced and discussed before they are implemented.

  1. Follow the path of railML 2.x in railML 3.x: downward compatibility will be guaranteed. Changes may lead to elements or attributes being deprecated, but not removed.
  2. Changes may lead to elements or attributes being deprecated. Elements and attributes that are deprecated in one minor version will be removed in the following minor version. Compatibility is only guaranteed between one minor version and the next.
  3. Changes may lead to elements or attributes being removed in a new minor version, without first being deprecated. No compatibility guaranteed.

Since railML is a standard made with the needs of the users strongly kept in mind, we would like to invite everyone to offer their feedback to these options. Please post any comments, concerns or suggestions in the forum post or contact Thomas Nygreen per email. Your feedback should be provided by August 31st to allow us to include it in the development of railML 3.2, scheduled for beta release around the end of 2020.

Update (January 6th, 2021)

The railML coordinators have discussed this further and agreed on a course of action. The decision made is to deprecate elements in the version after the current one and removing in the one after that (option number 2).

Go back