View source for Dev:Guideline for participating in the development process


'''Guideline for participating in the development process'''

This guideline is supposed to explain the development of the {{rml}} schema and how you can contribute.

As a developer of {{rml}}-based applications you may at some point reach limitations of {{rml}} or even discover bugs. As the schema is being developed in an open source style by the community, we invite you to help improving {{rml}} by reporting your demands and by participating in finding a solution.
==The provided development process==
===Enquiry===
Before demanding help by others, please examine this Wiki and the {{rml}} schema carefully. Maybe you can solve the problem yourself.

===Submit your issue to the forum===
If you find a bug or if you have a have demand for a new element or attribute, you shall bring it up in the {{site|https://www.railml.org/forum|{{rml}} forum|domain=forum}}. Maybe you will find a solution yourself when you formulate the question attentively. As an open community, other users, developers and coordinators will try to help you finding a solution for your issue. And sometimes the discussion will show, that something you considered to be a bug is in fact a feature, or that a feature you demanded already exists.

===Discussion process===
If your issue finds resonance, the subschema coordinator will moderate a discussion as to formulate a development task (or discard the issue). It is not recommended to contact the subschema coordinators before discussing the issue in the forum. However, to contact the coordinators directly, please see {{coordinators}}.

===Ticket===
As the result of the discussion process in the forum, the subschema coordinator will formulate the development task as a ticket as a {{ticket|2=2|3={{rml|2|link=no}} gitlab issue}} or a {{ticket|2=3|3={{rml|3}} gitlab issue}} respectively.

===Workaround===
The development process described above may take some time. If you need the requested element or attribute beforehand you may make use of the ''any element'' and ''any attribute'' in order to implement a fast workaround. This procedure is only possible if the relevant parent element contains an ''any anchor'' and if there is no other regular {{rml}} element or attribute where the information shall be stored. Please see [[dev:usingAny]] for a guide.

===Development within the Gitlab Repository===
The developers will coordinate the development of the new element or attribute within the respective Gitlab repository:
* For {{rml|2}}: {{gitlab||Gitlab repository for {{rml|2|link=no}}|version=2}}.
* For {{rml|3}}: {{gitlab||Gitlab repository for {{rml|3|link=no}}|version=3}}.
Although the {{rml}}'s repository is read-only to the public, we appreciate your contributions. Please, {{site|https://www.railml.org/en/contact.html|contact a coordinator|mode=silent}} to participate in this step.

===Release===
After the developers finish implementing the new elements or attributes as part of a new {{rml}} schema version, this schema version will be released. The release usually follows the version cycles of railML®. See [[Dev:Downloading_and_using_railML®]] to learn how to obtain the current schema, or download it directly from {{site|https://www.railml.org/en/developers/download.html}}.

===Contributing examples===
After the enhancement is published, you can improve the usability of railML® by contributing {{rml}} file examples from your expertise background.
<!-- A page [[dev:Examples]] is planned. please, add the link as soon as it is published. -->

===Incorporating the extension in the Wiki===
After release, the new element or attribute shall be incorporated into this Wiki documentation. The Wiki should always represent the currant state of the schema. Therefore:
* Don't document elements in the Wiki before them being published (or do so only if the publication date is known).
* After publication, take care, that changes are incorporated into the Wiki asap.
**New or changed attribute:
***Add or change the attribute in "attributes" providing its semantics with an [[template:intro|"Intro"-Template]] of the next proposed version
***Add or change the attribute to "constraints" providing its type
***If needed, declare another attribute 'deprecated' with the [[template:depr|"Depr"-Template]].
***Adjust the [[dev:XMLtree|XML-Tree]] — look for help [[Dev:How_to_join,_edit_and_create_the_railML_Wiki#Adjust_the_XML_tree|here]]
**new or changed sub-element
***Change the "children" with an "Intro"-Template of the next proposed version
***Provide a new Wiki page for the new sub-element — look for help [[Dev:How_to_join,_edit_and_create_the_railML_Wiki#Start_a_new_railML_Wiki_page_for_a_new_railML_element|here]]

{{interwiki}}
[[Category:GeneralDescription]]