diff --git a/documentation/SAFETYMANUAL.md b/documentation/SAFETYMANUAL.md new file mode 100644 index 00000000..1e59efa8 --- /dev/null +++ b/documentation/SAFETYMANUAL.md @@ -0,0 +1,164 @@ +# Disclaimer +This document does not replace a proper tool qualification in your +context. This document aims to guide you, and reduce the tool +qualification effort on your side. + +TRLC, including this safety manual, is distributed in the hope that +it will be useful, but WITHOUT ANY WARRANTY; without even the +implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR +PURPOSE. See the GNU General Public License for more details. + +This document shall become a safety manual in the sense of ISO +26262 ("Road vehicles – Functional safety"). +It might well apply to IEC 61508 +("Functional Safety of Electrical/Electronic/Programmable +Electronic Safety-related Systems"), too. +However, the safety manual is incomplete as of today. + + +# Safety Manual +## Introduction +You shall follow the instructions given in this document in order to +qualify the TRLC tool for the following context: + +This safety manual assumes you use the TRLC language and the TRLC tool for the following purpose: +- writing documents, especially requirement specification documents, +- using the TRLC tool in a CI (Continuous Integration) pipeline to + ensure that the written document adheres to the TRLC language as + specified in the Language Reference Manual. + +where [version 3.0 of the LRM](https://bmw-software-engineering.github.io/trlc/lrm-3.0.html) applies. + +Other purposes are not in the scope of this safety manual. + +Note: +This safety manual does not apply to the Python API, although the +TRLC tool relies on the Python API. +The tool and the API are different things and need separate use +case analyses. +Here we consider only use cases of the tool. + +## Definitions +The following definitions are given: +- TRLC files: + all files created by the user that are given to the TRLC tool as + input. + The tool considers only files ending on `.trlc` and `.rsl`. + Other files are ignored and are not considered input files. + +## Instructions +### Version Control System + +You shall use a version control system to store all TRLC files. + +Rationale: +Each TRLC object in a `.trlc` file has got an identifier. +The TRLC tool ensures that each identifier is unique. +But this uniqueness applies only to one moment in time, when the +TRLC tool runs. +TRLC Identifiers can be changed by the user. +Requirements shall have got a unique identifier throughout their +lifetime. +The commit identifier combined with the TRLC identifier provides +a mechanism to uniquely identify requirements during the whole +lifetime. + +Example: Use [git](https://git-scm.com/). + +### Always check the return code +Always check the return code of the TRLC tool. +It is not sufficient to analyze the command line output. + +If the return code is non-zero, then there has been at least one error detected. +If there is no command line output, there may still be errors. + +Rationale: +The command line output is not part of the tool qualification +strategy. +It will not be a qualified feature. +Only a tool return code of `0` shall guarantee that there are no +inconsistencies in the TRLC input files. + +Note: +When using TRLC in a pipe, make sure to handle the return code of +TRLC. +Pipes only return the return code of the last program in the pipe. +If TRLC is not the last program, then by default the pipe will not +handle the TRLC return code. + +### Validate Regular Expressions +If you use regular expressions (regex) in "check" statements, +then you shall qualify the Python function `re.match` against your +regex. +For this qualification you shall use the Python version which will +be used when running TRLC. + +If you do so, we encourage you to contribute your particular +qualification to this repository, for example as a system test. + +Rationale: +Qualifying `re.match` with arbitrary regular expressions is close +to impossible. + +### Ensure exact input +You shall take measure to ensure that the given TRLC input files +represent the complete set of requirements. + +Rationale: +If a TRLC file is not given as input to the TRLC tool, that file +might contain a duplicate definition of an identifier. +The TRLC tool will not detect that. + +## Review Lookup +You shall provide a method to find the documented review of a given +requirement. + +Example: +If you use GitHub pull requests to document reviews of requirements, +then you can use `git annotate` to find the pull requests (and +hence the reviews) related to a requirement. + +## Recommendations +### Renaming +It is highly recommended not to rename TRLC identifiers. +This makes it easier to track changes of TRLC objects back in time +across several commits. + +### GitHub Review Checklist + +It is highly recommended to use GitHub, and configure your CI system such that it inserts a checklist into the pull request's description whenever TRLC files are added, modified, or deleted. +The checklist shall guide the review of the requirements. +The checklist entries will be provided by your requirements +manager. + +Rationale: +Using a checklist during reviews of requirements is mandatory by +several standards. + +### Sanity Check for ASIL Inheritance + +It is highly recommended to install a CI job, that uses the +TRLC Python API (although currently not qualified), and checks +the inheritance of the ASIL attribute from one requirement to all its derived requirements. +The CI job shall forbid to merge a pull request which violates the +inheritance rule. + +Example: +If requirement `Req1` is marked with `ASIL=B`, and requirement +`Req2` is derived from `Req1`, then `Req2` shall have an ASIL value +in compliance with the ASIL decomposition and inheritance rules. +In general, `Req2` shall have `ASIL=B` as well. +A CI job can enforce these rules. + +### L.O.B.S.T.E.R. + +It is recommended to use +[LOBSTER](https://github.com/bmw-software-engineering/lobster) +- to ensure that all requirements are implemented, +- to provide a visual lookup table for all requirements. + +Note: +You need to provide a usable search function to your requirements +engineers. +You can do that by using the TRLC API, by using L.O.B.S.T.E.R., +or by some other means of (indexed) search function.