In a situation where good quality specifications already exist , it can be beneficial is essential to reuse them in a well planned manner. This is the case for the Automotive Virtual Platform definition developed within the HyperVisor project, which can build on the VIRTIO specification and potentially others.
This is often the case for an industry like automotive, in which OEMs want to leverage existing standards so that not every requirement needs to be written uniquely.
(As suppliers know, there are more than enough unique requirements ;-) Obviously
Obviously this is done all the time - consider for example requirements on the basic bolts and nuts of a physical assembly. It would almost always be done most often be done by referencing a standard, which in turn includes the requirements for the structural integrity and strength of the steel they are made of.
Developing industry-wide Open Standards and open source-code is what GENIVI is all about.
We see this pattern also in software/functional requirements:
...
This makes up a kind of hierarchy of documents similar to an upstream/downstream situation in open-source software projects. The documents will have a relationship. These document will range from general Often we will find generic (upstream, open standards) to applied in a more specific document (downstream / OEM requirement specification).
When If we can't use a specification to 100% as written, a delta-specification is neededwithout changes, then the difference needs to be handled. There are several options:
Suggest modifications first A) Prepare and suggest all modifications to the original specification as early as possible ("upstream first" principle in FOSS)
Forking B) Forking the original specification into a new variant
Writing C) Writing a new specification from scratch- Writing D) Writing a meta-specification (delta-specification) clarifying the applicability of the main specification. If we are significantly modifying or adding requirements
- If this is more than an applicability matrix then, we might rather call it a "delta-specification".
Considerations
Upstream Modification
The theoretically ideal approach is to affect the "upstream" to include our requirements representing the automotive industry. There may be trade-offs however. The For OEMs in particular, unfortunately many refer to the time it takes to convince other stakeholders and to get a new specification/code released could to be prohibitive. A specification might also of course become a "kitchen sink" if it tries to be everything for everyone.
Secondly, the focus of the stakeholders of the adopted (upstream) specification might be slightly different, or a fruitful discussion ends with the "agree to disagree" outcome. Applying embedded requirements onto a specification developed primarily by cloud server engineers might not always be a good fit.
For these reasons it might not always be appropriate possible to modify the original specification into exactly what is desired.
Forking
Forking is usually not a great approach because it causes a disconnect, despite that much of the information is and should be the same. This disconnect causes the projects to drift apart and the effort of "keeping up to date" increases.
- Several aspects to consider:
- License conditions must allow it, of courseof course must allow the content to be copied & modified. (F)(L)OSS licenses are the most common example.
- Good citizen / good behavior. (In open source, there is the concept of a hostile fork).
- Avoiding Avoid any confusion between versions/variants.
- → This It is rarely a good approach !but is explicitly allowed by licenses and it might be right to apply when it is appropriate.
If a fork is If it's done, using best-practices for software is recommended (such as . We should aim to keep the specification in plain text-format and use a git repository). But even with this it's very difficult to keep , that allows efficient diffing and merging. This is to make maintenance and interaction with the upstream even manageable. Even with these tools there is a lot of work to keep a combination of "patches" to a specification from becoming contradictory or illogical. There are no compilers and automated unit-tests to check your modified work.../combined work, as is done with software.
Applicability matrix / meta- / delta-specification
Very often a good compromise is the applicability matrix approach - or if slightly more differences are expected, writing a delta-specification.
This is a very useful way It has the potential to create a formal short, clear, and unambiguous specification that still fits exactly to ones needs, while avoiding proliferation of multiple overlapping documents. It is a kind of "meta-specification" that because is one level above, and refers down to the others. (*Normally But perhaps a "meta-specification" probably strictly means a specification that defines how specifications should be written, so we can adopt the name delta (difference) -specification seems appropriate)here.
Delta Specification format
When creating a specification by referencing existing ones we should consider the following:?
- Reuse Decide which parts of the specification to reuse (by reference) as a whole and rewrite others
- Reuse with references and modifications
- , and which ones will be clearer and better by rewriting them.
- When only some Only parts of the general specification might be applicable. Modify is applicable we must modify referenced specifications by an applicability list or matrix.,
still meeting these goals:- Completeness
- Avoiding ambiguity
- Clarify how to handle conflicts and inconsistencies. (What takes precedence)
- Finally, we shall add unique requirements in a way that is not too difficult to manage.
- The tradeoffs here are between reducing repetition and divergence, versus complexity for both the reader and writer. When referring to a combination of multiple documents, it can could lead to ambiguity or at least making make the consumption of the specification very difficult and impractical.
Principles:
- Each chapter should define the requirements by minimal repetition, by referring to already written text
- Sometimes, for clarity some limited copying/repetition is however desired for clarity, overriding rule 1. Consider both the convenience of specification writers/maintainers and that of the consumers of the specification.
- Modifications can be done by adding additional text that slightly changes as a modifier to what the original spec requiresstates. This still avoids repeating a lot of the major work that went into the original.
- In particular consider remember that in the applicability definitions, things like "optional", "conditional" and "mandatory" can be modified compared to the original specification.
For example, something that is well defined but stated as optional in a referred specification can be made mandatory according to our requirements.
...
Exampleexample:
Automotive Virtual Platform Specification, version
...
0.9
1. Introduction
Purpose, Scope, goals, context, applicability...
2. Architecture
Assumptions made about the architecture, use-cases...
Limits to applicability, etc...
3. General requirements
Automotive requirements to be met (general)...
3. Virtual Device Requirements
3.1 Serial Device
3.1.1 Standard Serial Device
REQ-1: Follow chapter Requirement according to chapter x.y in [VIRTIO].
REQ-1.2: Exception: Requirements 4 and 6 in that chapter shall not be implemented.
3.1.2 Network device exposed as serial device
For this special type there are some additional requirements.
REQ-2: Requirement according to chapter 3 in [VIRTIO]
REQ-3: The virtual device MUST provide an auxiliary programming interface (e.g. ioctl on POSIX) with the following featurefeatures:
- feature 1
- feature 2 .... blah
3.2 Block Device
REQ-34: Follow According to chapter 4.5.6 in [VIRTIO] and chapter 45.2.1 in [Other spec]
REQ-4.1: When applying REQ-3, if there are conflicting requirements (note: disk performance, chapter 4.9.9), the requirement in [Other spec] shall take precedence.
REQ-54.2: Device type Foo, listed as optional, shall here be mandatory.
REQ-65: Device type Bar , listed as mandatory described in chapter 1.2.3 in [Other spec], shall here be conditional:conditionally implemented:
a. When implementing a system of type A, Bar is optional.
c. When implementing a system of type B, Bar shall be mandatory.
b. When implementing a system of type C, Bar shall be mandatory with the following modification of chapter 1.2.3
....
3. References
[VIRTIO] Virtual I/O Device (VIRTIO) Version 1.0, Committee Specification 04, release 03 March 2016.
...