Functional requirements {#f}¶ ↑
[core] Core {#core}¶ ↑
[core.req] Requirement {#core-req}¶ ↑
The System shall provide the Requirement
entity.
[core.req.data] Requirement data {#core-req-data}¶ ↑
The System shall provide the following data elements for Requirement
entity:
Name | Type | M | Description :——— | —————— | - | :————————————- id | String | Y | Unique requirement identifier title | String | Y | Requirement title attributes | Hash | N | Requirement attributes body | Text | Y | Requirement body parent | Reference | N | Reference to parent requirement object items | Array | N | Array of child requirement entities
[core.req.file] Reading requirement from a file {#core-req-file}¶ ↑
The System shall provide the ability to read Requirement from the formatted Markdown file. An example of this formatted Markdown file is provided below.
# [<requirement id>] <requirement title> {{ <attribute1>: value1 <attribute2>: value2 }} <body> ## [<child requirement id>] <child requirement title> <child requirement body
[core.req.file.attr] Attributes excerpt {#core-req-file-attr}¶ ↑
The System shall parse section {{ }}
as the hash of requirement attributes. Attributes section might follow (the section is optional) the header section. The header section might be separated from attributes section by an empty line or a line of spaces.
[core.req.file.attr.key] Key and Value {#core-req-file-attr-key}¶ ↑
The System shall support attribute keys written as a sequence of [a-z,A-Z,._]
characters finished by a colon :
and followed by a space. The remainder of the line must be determined as attribute value.
[core.req.file.attr.sys] System attributes {#core-req-file-attr-sys}¶ ↑
The System shall support the following list of system attributes. This attributes must be interpreted in a special way.
Attribute | Value | Description :———- | :—- | ————————————————– parent | [id] | Reference to parent requirement suppress_id | true | Suppress output of the requirement id in header while creating a document. child_order | text | Order of child requirements while creating a document.
[core.req.file.struct] Headers structure {#core-req-file-struct}¶ ↑
The System shall parse at least three levels of markdown headers structure. Headers with low level and its paragraphs must be parsed as child requirements and placed into the appropriate items
array of its parent requirement.
[core.doc] Document {#core-doc}¶ ↑
The System shall provide the Document
entity.
[core.doc.data] Document data {#core-doc-data}¶ ↑
The System shall provide the following data elements for Document
entity:
Name | Type | M | Description :—- | ————- | - | :———————————- items | Requirement[] | N | Array of top requirement entities
[core.doc.load] Requirements loading {#core-doc-load}¶ ↑
The System shall provide the ability to load all requirements files in an a relevant directory of file system into Document
entity. TBD: move dierectory as function parameter
[core.doc.load.hrch] Hierarchy building {#core-doc-load-hrch}¶ ↑
When all files are loaded, the System shall build the right requirements hierarchy through the parent
attribute (see [core.req.file.attr.sys] System attributes and [core.req.file.struct] Headers structure).
[core.doc.load.sort] Sort child requirements {#core-doc-load-sort}¶ ↑
When all files are loaded, if any requirement has a child_order
system attribute, the System shall sort its child requirements according to the attribute value.
[core.doc.chk] Check requirements {#core-doc-chk}¶ ↑
The System shall provide the ability to check loaded requirements for the following errors: * duplicates of requirement ids among requirement files; * wrong links to other requirements in requirement body.
[core.doc.chk.dup] Duplicate id {#core-doc-chk-dup}¶ ↑
TBD: provide description
[core.doc.chk.lnk] Wrong links {#core-doc-chk-lnk}¶ ↑
TBD: provide description
[core.doc.create] Create requirements document {#core-doc-create}¶ ↑
The System shall provide the ability to create a requirements document file. This file must contain all requirements loaded in the Document
entity. This file must be a well-formed Markdown file.
[core.doc.create.header] Writing headers {#core-doc-create-header}¶ ↑
The System shall write requirement header as a standard Markdown header # [id] title\n
. The level of header must be calculated through the requirement depth in requirement hierarchy.
[core.doc.create.header.skipid] 'suppress_id' system attribute {#core-doc-create-header-skipid}¶ ↑
When requirement contains a special attribute {{suppress_id: true}}
, the System shall suppress the [id]
output part of header.
[core.doc.create.attr] Attributes section {#core-doc-create-attr}¶ ↑
When requirement contains any attributes except special attributes (see [core.req.file.attr.sys] System attributes), the System shall write a table of attributes after requirement header in the following way.
Attribute | Value :———- | :—— attribute 1 | value 1 attribute 2 | value 2
[core.doc.create.body.links] Replace links macro {#core-doc-create-body-links}¶ ↑
When requirement body contains links macros with other requirements [[requirement id]]
, the System shall replace these links macros with the right link to requirement in the target document.
[core.doc.create.check] Check document for errors {#core-doc-create-check}¶ ↑
Before creating a document, the System shall check Document
entity for errors (see [core.doc.chk] Check requirements for details). When any error is found, the System shall abort execution of create document
and show a list of errors.
[dsl] DSLs {#dsl}¶ ↑
[dsl.trace] Trace DSL {#dsl-trace}¶ ↑
The System shall provide Trace DSL
for tracing requirements to other project artifacts like tests, source code, different guides, etc.
An example of Tracing DSL
is as follows..
skip 'func', 'top level topic' skip 'nonf', 'top level topic' from 'id.1', :source, 'src/id.1.rb' from 'id.1', :test, 'src/id.1.spec.rb' from 'id.2', :source, ['lib/id.1.rb', 'lib/id.1.helper.rb'] from 'id.2', :test, ['spec/id.1.spec.rb'] from 'id.2', :guide, ['doc/user-guide', 'doc/admin-guide']
[dsl.trace.skip] Skip {#dsl-trace-skip}¶ ↑
The System shall provide Tracing DSL
function skip
. This function just places requirement id to skipped area.
The skip
function must accept the following parameters.
Parameter | Type | M | Description :———- | —————- | - | :—————– object | Object
, Object[] | Y | Skipped object description | String | N | Reason of skipping
[dsl.trace.from] From {#dsl-trace-from}¶ ↑
The System shall provide Tracing DSL
function from
to add traces to the object.
The from
function must accept the following parameters.
Parameter | Type | M | Description :———— | —————- | - | :———————————————————– traced object | Object
| Y | traced object (from) type | String, Symbol | Y | Kind of trace from source object to the target object (type) target object | String, String[] | Y | target object (to)
[dsl.pert] PERT DSL {#dsl-pert}¶ ↑
The System shall provide PERT DSL
to estimate software development effort by PERT method (See PERT method overview (rus)). An example of PERT DSL
file is as follows.
skip 'ident', 'top level header' pert 'ident.1', o: 10, m: 14, p: 22 pert 'ident.2', o: 10, m: 14, p: 22 pert 'ident.3', o: 10, m: 14, p: 22 # puts calculate
[dsl.pert.skip] Skip {#dsl-pert-skip}¶ ↑
The System shall provide PERT DSL
function skip
. This function shall have the same meaning, parameters and behavior as Tracing DSL
function skip
[dsl.trace.skip] Skip
[dsl.trace.pert] Pert {#dsl-trace-pert}¶ ↑
The System shall provide PERT DSL
function pert
to evaluate PERT estimations of effort and error for the object development.
The pert
function must accept the following parameters.
Parameter | Type | M | Description :——– | —— | - | :——————— object | Object
| Y | Estimated object o: | Number | Y | Optimistic estimation m: | Number | Y | Most usual estimation p: | Number | Y | Pessimistic estimation
The pert
function must return hash of effort and error values {effort: 37, error: 3}
[dsl.pert.calc] Calculate {#dsl-pert-calc}¶ ↑
The System shall provide function calculate
for PERT DSL
. This function shall calculate summary effort, error and effort95% and return hash of the calculations result {effort: 47, error: 12, e95: 51}
.
Calculation result of PERT DSL
function calculate
Key | Type | Description :—– | :—– | :————————————————- effort | Number | Summary effort error | Number | Average error e95 | Number | Summary effort with 95% TBD: what this right name?
[dsl.pert.dup] Duplicates {#dsl-pert-dup}¶ ↑
When an estimation is being added through skip
and pert
functions, if requirement with the same id is already estimated, the System shall abort the execution with the following error message Requirement <id> is already estimated. Operation aborted.
[dsl.fpa] FPA DSL {#dsl-fpa}¶ ↑
The System shall provide FPA DSL
to estimate software development effort by Function Point Analysis (FPA) methodology. An example of FAP DSL
file is as follows.
ILF 'Product', det: 20, ret: 3 ILF 'Customer', det: 20, ret: 2 ILF 'Order', det: 10, ret: 1 EO 'CustomerView', det: 20, ftr: 1 EI 'CustomerEdit', det: 20, ftr: 2 EQ 'CustomerEdit', det: 20, ftr: 2 characteristics ({ data_communications: 0, distributed_data_processing: 0, performance: 0}) # calculate
[dsl.fpa.skip] Skip {#dsl-fpa-skip}¶ ↑
The System shall provide FPA DSL
function skip
. This function shall have the same meaning, parameters and behavior as Tracing DSL
function skip
[dsl.trace.skip] Skip
[dsl.fpa.ilf] ILF (Internal Logical File) {#dsl-fpa-ilf}¶ ↑
The System shall provide FPA DSL
function ILF
to add new ILF estimation for object.
The ILF
function must accept the following parameters.
Parameter | Type | M | Description :——– | —— | - | :——————— object | Object
| Y | Estimated object det: | Number | Y | Number of Data element type ret: | Number | Y | Number of Record element type
[dsl.fpa.eif] EIF (External Interface File) {#dsl-fpa-eif}¶ ↑
The System shall provide FPA DSL
function EIF
to add new EIF estimation for object.
The EIF
function must accept the following parameters.
Parameter | Type | M | Description :——– | —— | - | :——————— object | Object
| Y | Estimated object det: | Number | Y | Number of Data element type ret: | Number | Y | Number of Record element type
[dsl.fpa.ei] EI (External Input) {#dsl-fpa-ei}¶ ↑
The System shall provide FPA DSL
function EI
to add new EI estimation for object.
The EI
function must accept the following parameters.
Parameter | Type | M | Description :——– | —— | - | :——————— object | Object
| Y | Estimated object det: | Number | Y | Number of Data element type ftr: | Number | Y | Number of File type record
[dsl.fpa.eo] EO (External Output) {#dsl-fpa-eo}¶ ↑
The System shall provide FPA DSL
function EO
to add new EO estimation for object.
The EO
function must accept the following parameters.
Parameter | Type | M | Description :——– | —— | - | :——————— object | Object
| Y | Estimated object det: | Number | Y | Number of Data element type ftr: | Number | Y | Number of File type record
[dsl.fpa.eq] EQ (External Inquiry) {#dsl-fpa-eq}¶ ↑
The System shall provide FPA DSL
function EQ
to add new EI estimation for object.
The EQ
function must accept the following parameters.
Parameter | Type | M | Description :——– | —— | - | :——————— object | Object
| Y | Estimated object det: | Number | Y | Number of Data element type ftr: | Number | Y | Number of File type record
[dsl.fpa.sysch] Characteristics {#dsl-fpa-sysch}¶ ↑
The System shall provide FPA DSL
function characteristics
to provide adjustment information about system characteristics for full estimation.
The EQ
function must accept the following parameters.
Parameter | Type | M | Description :————– | —- | - | :—————————– characteristics | Hash | Y | Hash of system characteristics
[dsl.fpa.calc] Calculate {#dsl-fpa-calc}¶ ↑
The System shall provide function calculate
for FPA DSL
. This function shall calculate number of unadjusted function points, adjustment factor and number of function points and return hash of the calculation result {{ufp: 57, vaf: 0.65, fp: 45}}
.
Calculation result of FPA DSL
function calculate
Key | Type | Description :– | :—– | :———————————- ufp | Number | Total of unadjusted function points vaf | Number | Adjustment factor value fp | Number | Total of fnction points
[dsl.fpa.dup] Duplicates {#dsl-fpa-dup}¶ ↑
When an estimations is being added through skip
or ILF, EIF, EO, EI, EQ
functions, if requirement with the same id is already estimated, the System shall abort the execution with the following error message Requirement <id> is already estimated. Operation aborted.
[i] Interface requirements {#i}¶ ↑
[cli] Command line interface {#cli}¶ ↑
[cli.core] Essential commands {#cli-core}¶ ↑
[cli.req] req command {#cli-req}¶ ↑
The System shall provide CLI command req
. When req
command received, the System shall create a well-formed Markdown file which represents requirement entity
(see [core.req.data] Requirement data and [core.req.file] Reading requirement from a file for details).
[cli.req.param] Parameters {#cli-req-param}¶ ↑
The System shall provide the following parameters for the req
command.
Name | Type | M | Default | Description :——— | —— | - | ——- | :—————————— id | String | Y | | Unique requirement identifier title | String | N | | Requirement tile attributes | Hash | N | | Requirement attributes template | String | N | | Template for the requirement body
[cli.req.param.attr] Attributes parameter provided {#cli-req-param-attr}¶ ↑
When Attributes
parameter is provided for req
command, the System shall add attributes excerpt
to output file. See [core.req.file.attr] Attributes excerpt for details.
[cli.req.param.tmpl] Template parameter provided {#cli-req-param-tmpl}¶ ↑
When Template
parameter is provided for req
command, the System shall place the text form template file to requirement body.
[cli.req.param.tmpl.mid] Template macro @@id {#cli-req-param-tmpl-mid}¶ ↑
The System shall replace macro text @@id
in template text by id
parameter.
[cli.req.param.tmpl.mtt] Template macro @@title {#cli-req-param-tmpl-mtt}¶ ↑
The System shall replace macro text @@title
in template text by title
parameter.
Suppose, you have a template action_template.md
with the following content.
The System shall provide action `@@title`. ## [@@id.para] Parameters The System shall provide the following parameters for the `@@title` action. ## [@@id.flow] Flow The System shall provide the following execution flow for the `@@title` action.
When the System executes req
command get action.foo "Foo" -t=action_template.md
(a template action_template.md
is provided as a parameter), the output file will have the following content.
# [action.foo] Foo The System shall provide action `Foo`. ## [action.foo.para] Parameters The System shall provide the following parameters for the `Foo` action. ## [action.foo.flow] Flow The System shall provide the following execution flow for the `Foo` action.
[cli.req.file.name] File name {#cli-req-file-name}¶ ↑
The System shall name the output file as <id>.md
.
[cli.req.file.name.exist] Requirement file exists {#cli-req-file-name-exist}¶ ↑
When requirement file with the same name exists in file system, the command req
shall indicate the error message File <file_name> already exists. Operation aborted.
and abort the command execution.
[cli.doc] doc command {#cli-doc}¶ ↑
The System shall provide CLI command doc
. When command doc
received, the System shall create requirements document requirements.md
(well-formed markdown file) from requirements files. All necessary information about document creation is pointed in [core.doc.create] Create requirements document section.
[cli.doc.file] Rewriting requirements.md {#cli-doc-file}¶ ↑
The System shall rewrite file requirements.md
if it exists.
[cli.chk] chk command {#cli-chk}¶ ↑
The System shall provide CLI command chk
. When command chk
received, the System shall check requirement files for errors and return the found errors. By fact, chk
command is a CLI interface to Check requirements
core function (see [core.doc.chk] Check requirements for details)
[cli.trace] 'trace' command family {#cli-trace}¶ ↑
[cli.trace.check] trace check command {#cli-trace-check}¶ ↑
The System shall provide CLI command trace check
. When the command trace check
is received, the System shall check Tracing DSL
file traces.trc
for: * missed traces
(see [cli.trace.update.missed] Missed traces) and return array of missed requirement ids. * wrong traces
(see [cli.trace.check.wrong] Wrong trace) and return array of wrong object ids.
[cli.trace.check.wrong] Wrong trace {#cli-trace-check-wrong}¶ ↑
Wrong traces are the ones from traces.trc
file added through skip
and from
functions, but the referenced requirement id is not found in requirements repository.
[cli.trace.check.precheck] Precheck {#cli-trace-check-precheck}¶ ↑
When Tracing DSL
file traces.trc
does not exist, the System shall abort execution of the command trace update
and show an error message Tracing file traces.trc does not exist. Operation aborted.
.
[cli.trace.create] trace create command {#cli-trace-create}¶ ↑
The System shall provide CLI command trace create
. When command trace create
is received, the System shall create a well-formed Tracing DSL
file called traces.trc
, which is based on requirements repository.
[cli.trace.create.check] Precheck {#cli-trace-create-check}¶ ↑
When Tracing DSL
file traces.trc
exists, the System shall abort execution of trace create
command and show an error message Tracing file traces.trc already exists. Operation aborted.
.
[cli.trace.create.record] Trace record {#cli-trace-create-record}¶ ↑
The System shall add trace records based on requirement data.
When requirement body is empty, the System shall add a requirement through function skip '<id>', 'requirement body is empty'
.
When requirement body is not empty, the System shall add a requirement trace through function from '<id>', :source, 'replace to tracing object'
[cli.trace.update] trace update command {#cli-trace-update}¶ ↑
The System shall provide CLI command trace update
. When command trace update
is received, the System shall add the missed traces to Tracing DSL
file called traces.trc
from requirements repository (project/req/*.md
files).
During an update process, the System shall use the same behavior as described in [cli.trace.create.record] Trace record
[cli.trace.update.missed] Missed traces {#cli-trace-update-missed}¶ ↑
Missed traces
are requirements presented in Requirements Repository
but not included in Tracing DSL
file traces.trc
through skip
or from
DSL function.
[cli.trace.update.check] Precheck {#cli-trace-update-check}¶ ↑
When Tracing DSL
file traces.trc
does not exist, the System shall abort execution of the command trace update
and show an error message Tracing file traces.trc does not exist. Operation aborted.
.
[cli.pert] 'pert' command family {#cli-pert}¶ ↑
[cli.pert.check] pert check command {#cli-pert-check}¶ ↑
The System shall provide CLI command pert check
. When command pert check
is received, the System shall check PERT DSL
file estimation.pert
for: * missed estimations
(see [cli.pert.update.missed] Missed estimations) and return the array of missed requirement ids. * wrong estimations
(see [cli.pert.check.wrong] Wrong estimations) and return the array of wrong object ids.
[cli.pert.check.wrong] Wrong estimations {#cli-pert-check-wrong}¶ ↑
Wrong estimations are the ones from estimation.pert
file added through skip
and pert
functions, but the referenced requirement id is not found in requirements repository.
[cli.pert.check.precheck] Precheck {#cli-pert-check-precheck}¶ ↑
When PERT DSL
file estimation.pert
does not exist, the System shall abort execution of the command pert check
and show the error message PERT estimation file estimation.pert does not exist. Operation aborted.
.
[cli.pert.create] pert create command {#cli-pert-create}¶ ↑
The System shall provide CLI command pert create
. When command pert create
is received, the System shall create a well-formed PERT DSL
file called estimation.pert
, which is based on Requirements repository
.
[cli.pert.create.check] Precheck {#cli-pert-create-check}¶ ↑
When PERT DSL
file estimation.pert
exists, the System shall abort execution of the command pert create
and show the error message PERT file estimation.pert already exists. Operation aborted.
.
[cli.pert.create.record] Pert record {#cli-pert-create-record}¶ ↑
The System shall add PERT estimation records based on requirement data.
When requirement body is empty, the System shall add the requirement through the function skip '<id>', 'requirement body is empty'
.
When requirement body is not empty, the System shall add the requirement estimation through the function pert '<id>', o: 0, m: 0, p: 0
.
[cli.pert.update] pert update command {#cli-pert-update}¶ ↑
The System shall provide CLI command pert update
. When command pert update
is received, the System shall add missed estimations to PERT DSL
file called estimation.pert
from requirements repository (project/req/*.md
files).
During an update process, the System shall use the same behavior as described in [cli.pert.create.record] Pert record
[cli.pert.update.missed] Missed estimations {#cli-pert-update-missed}¶ ↑
Missed estimations
are requirements presented in requirements repository but not included in PERT DSL
file estimation.pert
through skip
or pert
DSL function.
[cli.pert.update.check] Precheck {#cli-pert-update-check}¶ ↑
When PERT DSL
file estimation.pert
does not exist, the System shall abort execution of the command pert update
and show error message PERT estimation file estimation.pert does not exist. Operation aborted.
.
[cli.fpa] 'fpa' command family {#cli-fpa}¶ ↑
[cli.fpa.check] fpa check command {#cli-fpa-check}¶ ↑
The System shall provide CLI command fpa check
. When the command fpa check
is received, the System shall check FPA DSL
file estimation.fpa
for: * missed estimations
(see [cli.fpa.update.missed] Missed estimations) and return the array of missed requirement ids. * wrong estimations
(see [cli.fpa.check.wrong] Wrong estimations) and return the array of wrong object ids.
[cli.fpa.check.wrong] Wrong estimations {#cli-fpa-check-wrong}¶ ↑
Wrong estimations are the ones from estimation.fpa
file added through functions skip
or pert
, but the referenced requirement id is not found in requirements repository.
[cli.fpa.check.precheck] Precheck {#cli-fpa-check-precheck}¶ ↑
When FPA DSL
file estimation.fpa
does not exist, the System shall abort execution of the command fpa check
and show error message FPA estimation file estimation.fpa does not exist. Operation aborted.
.
[cli.fpa.create] fpa create command {#cli-fpa-create}¶ ↑
The System shall provide CLI command fpa create
. When command FPA create
is received, the System shall create a well-formed FPA DSL
file called estimation.fpa
, which is based on Requirements repository
.
[cli.fpa.create.check] Precheck {#cli-fpa-create-check}¶ ↑
When FPA DSL
file estimation.fpa
exists, the System shall abort execution of the command fpa create
and show the error message FPA file estimation.fpa already exists. Operation aborted.
.
[cli.fpa.create.record] FPA record {#cli-fpa-create-record}¶ ↑
The System shall add FPA estimation records based on requirement data.
When requirement body is empty, the System shall add the requirement through skip '<id>', 'requirement body is empty'
.
When requirement body is not empty, the System shall add the requirement estimation through ILF '<id>', det: 0, ret: 0
. TBD: This combination of parameters values must raise error in check
command.
[cli.fpa.update] fpa update command {#cli-fpa-update}¶ ↑
The System shall provide CLI command fpa update
. When the command fpa update
is received, the System shall add the missed estimations to FPA DSL
file called estimation.fpa
from requirements repository (project/req/*.md
files).
During an update process, the System shall use the same behavior as described in [cli.fpa.create.record] FPA record
[cli.fpa.update.missed] Missed estimations {#cli-fpa-update-missed}¶ ↑
Missed estimations
are requirements presented in requirements repository but not included in FPA DSL
file estimation.fpa
through skip
or ILF, EIF, EO, EI, EQ
DSL function.
[cli.fpa.update.check] Precheck {#cli-fpa-update-check}¶ ↑
When FPA DSL
file estimation.fpa
does not exist, the System shall abort execution of the command fpa update
and show the error message FPA estimation file estimation.fpa does not exist. Operation aborted.
.