Verification Artifacts Styleguide

All text documents that are requested to be verified shall provide line numberings within the document. the line numbering shall cover the complete document and start from line 1 and end with the last line of the last page. The numbering shall be continued when beginning a new page. Empy lines are not numbered. Tables figures and pictures shall be numbered with a separate line underneath the table, figures or picure.

(Proposal of 2013-10-14)

Interface Variables must be standardised.

Please use semantic versioning explained here: http://semver.org/spec/v2.0.0.html

Variables Namings are separated between internal (inside the EVC- Kernel) and external variables (used for communication between the EVC - Kernel and the interfaces). (see D2.4) All external variables are described inside the following documents:

1. openETCS API documentation
2. Subset-026-7
3. to be completed

External and internal variables are announced to the data dictionary. (role and way to be defined)

Only variables accepted by the data dictionary are allowed to be used as variables inside the model.

The mapping between external and internal variables are defined inside the data dictionary.

Data Dictionary

The data dictionary will evolve over time and thus the need to have a synchronised set of variables has been identified a crucial part in a distributed development.

The proposal is to have a common document inside github with the following properties:

1. The name of the document is: "openETCSDataDictionary.xml"

2. The document is encoded with Extensible Markup Language (XML) see Extensible Markup Language Definition

3. All contributions to the document are launched as a pull request

4. Each variable will be represented within one xml- block consisting of

5. Variable name (see naming converntions within D2.4)

6. Variable type (see SysML Version 1.3 definition June 2012 and ISO/IEC 9899:TC2 specification)

7. Variable Range

8. Variable source (the name of the function or name of the interface the variable is derived from)

9. Requirements link either the use of the variable is defined or, if available, the variable itself is defined(see naming convention within D2.4)

10. Risk: possible ambiguity used for refinement of data dictionary, proposals e.g. to replace one variable by differentiating two aspects can be filed here (free text, string for later reuse)

11. The data dictionary will reside inside the SSRS Repository under the responsibility of the SSRS task leader.

12. Merging the block into the repository will be done according to the rules set within the SSRS task

13. Merging of the block related to the variable into the XML file master branch means that the variable has been

14. Checked for redundancy within the data dictionary

15. Checked for naming conventions and restrictions are met (defined within D2.4)

16. Checked that all information related to the variable is given

17. Approved and accepted by the SSRS team

Internal Functions

Naming of internal functions

Internal functions are named using an active form consisting of at least a combination of a verb and an object

Example:

1. initiateTerminatingASession

Internal variables

Naming of internal variables

The naming of the variables should consist of at least a combination of a verb and an object using the passive form

Examples:

1. orderReceivedFromTrackside for a structure
2. endOfMissionIsExecuted for a boolean

Property of internal Variables

1. Can be correlated to external variables
2. Used to create internal functions
3. The source the internal variable is derived from is given in the name of the function
4. The variable type is defined within SysML Version 1.3 definition June 2012 and ISO/IEC 9899:TC2 specification)