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

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..

[api] API {#api}

[web] Web application {#web}

Non-functional requirements {#n}

Design constraints {#d}