Merge pull request #149 from itsallcode/story/115-Passdown_specification_items

Story/115 passdown specification items

Author: kaklakariada

.circleci/config.yml

@@ -35,4 +35,3 @@ jobs:
 
       - store_test_results:
           path: target/surefire-reports
-

doc/design.md

@@ -87,7 +87,7 @@ Since the specification item IDs inherently look similar, load tests need to sho
 ## Importers
 For each specification artifact type OFT uses an importer. The importer uses the specification artifact as data source and reads specification items from it.
 
-## Import Event Listeners
+## Import Event Listener
 Importers emit events if they find parts of a [specification item](#specification-item) in the artifact they are importing.
 
 ### Specification List Builder
@@ -336,7 +336,7 @@ Needs: impl, itest
 ### Internal Data Structures
 
 #### Specification Item
-`dsn~specification-item~2`
+`dsn~specification-item~3`
 
 A `SpecificationItem` consists of the following parts:
 
@@ -351,10 +351,16 @@ A `SpecificationItem` consists of the following parts:
 * Depends (List of `SpecificationItemId`, optional)
 * Needs (List of `String`, optional)
 * Tags (List of `String`, optional)
+* Forwards (`boolean`, internal)
+
+Comment:
+
+See `req~forwarding_needed_coverage~1` for an explanation of the "forwards" fields meaning.
 
 Covers:
 
 * `req~specification-item~2`
+* `req~forwarding_needed_coverage~1`
 
 Needs: impl, utest
 
@@ -395,13 +401,13 @@ Needs: impl, utest
 A requirement ID has the following format
 
     requirement-id = type "~" id "~" revision
-
+    
     type = 1*ALPHA
-
+    
     id = id-fragment *("." id-fragment)
-
+    
     id-fragment = ALPHA *(ALPHA / DIGIT / "_" / "-")
-
+    
     revision = 1*DIGIT
 
 Rationale:
@@ -435,6 +441,7 @@ Markdown titles show up in the outline and are a natural way of defining a requi
 Covers:
 
 * `req~markdown-standard-syntax~1`
+* `req~markdown-outline-readable~1`
 
 Needs: impl, utest
 
@@ -444,9 +451,9 @@ Needs: impl, utest
 In Markdown specification item references have the following format:
 
     reference = (plain-reference / url-style-link)
-
+    
     plain-reference = requirement-id
-
+    
     url-style-link = "[" link-text "]" "(" "#" requirement-id ")"
 
 Covers:
@@ -461,9 +468,9 @@ Needs: impl, utest
 The Markdown Importer supports the following format for links that cover a different specification item.
 
     covers-list = covers-header 1*(LINEBREAK covers-line)
-
+    
     covers-header = "Covers:" *WSP
-
+    
     covers-line = *WSP "*" *WSP reference
 
 Only one traced reference per line is supported. Any optional text after the reference is ignored if it is separated by at least one whitespace character
@@ -484,9 +491,9 @@ Needs: impl, utest
 The Markdown Importer supports the following format for links to a different specification item which the current depends on.
 
     depends-list = depends-header 1*(LINEBREAK depends-line)
-
+    
     depends-header = "Depends:" *WSP
-
+    
     depends-line = *WSP "*" *WSP reference
 
 Only one traced reference per line is supported. Any optional text after the reference is ignored if it is separated by at least one whitespace character
@@ -522,6 +529,30 @@ Covers:
 
 Needs: impl, utest
 
+#### Markdown Artifact Forwarding Notation
+`dsn~md.artifact-forwarding-notation~1`
+
+The Markdown Importer supports forwarding required coverage from one artifact type to one or more different artifact types using the following notation.
+
+    artifact-need-redirection = skipped-artifact-type *WSP "-->" *WSP target-artifact-list
+        *WSP ":" *WSP original-requirement-id
+        
+    skipped-artifact-type = artifact-type
+    
+    target-artifact-list = artifact-type *("," *WSP artifact-type)
+        
+    original-requirement-id = requirement-id
+
+The following example shows an architectural specification item that forwards the needed coverage directly to the detailed design and an integration test.
+
+    arch --> dsn, itest : req~skip-this-requirement~1
+ 
+Covers:
+
+* `req~artifact-type-forwarding-in-markdown~1`
+
+Needs: impl, utest
+
 ### Elektrobit Markdown-style Structures
 
 #### Markdown "Needs" List

doc/system_requirements.md

@@ -183,6 +183,21 @@ Tags are a way to label an artifact intended for grouping.
 
 Needs: dsn
 
+#### Forwarding Needed Coverage
+`req~forwarding_needed_coverage~1`
+
+OFT allows users to forward needed coverage from one artifact type to one or more different types.
+
+Rationale:
+
+Often a system requirement does not affect the high-level architecture. In this case it is convenient for the architect to hand it down to lower levels directly.
+
+Covers:
+
+* [feat~markdown-import~1](#markdown-import)
+
+Needs: dsn
+
 ### Supported Formats
 
 #### Markdown
@@ -211,6 +226,8 @@ Covers:
 Needs: dsn
 
 ##### Markdown Outline Readable
+`req~markdown-outline-readable~1`
+
 The Markdown outline -- a table of contents created from the heading structure by various Markdown editors -- must be human readable.
 
 Rationale:
@@ -238,6 +255,21 @@ Covers:
 
 Needs: dsn
 
+##### Artifact Type Forwarding in Markdown
+`req~artifact-type-forwarding-in-markdown~1`
+
+The Markdown format features a compact way to forward a requirement from the artifact type that was originally required to one or more different artifact types.
+
+Rationale:
+
+Often a system requirement does not affect the high-level architecture. In this case it is convenient for the architect to hand it down to lower levels directly.
+
+Covers:
+
+* [feat~markdown-import~1](#markdown-import)
+
+Needs: dsn
+
 #### Coverage Tags
 
 Developers add coverage tags as comments to the source code to indicate where certain specification items are covered.

doc/user_guide.md

@@ -1,6 +1,6 @@
 <head><link href="oft_spec.css" rel="stylesheet"></link></head>
 
-![oft-logo](../src/main/resources/openfasttrack_logo.svg)
+![oft-logo](../src/main/resources/openfasttrace_logo.svg)
 
 # OpenFastTrace (OFT) User Guide
 
@@ -235,6 +235,18 @@ Requirements should be accompanied by a rationale in all cases where the reason
 
     Needs: dsn 
 
+### Delegating Requirement Coverage
+
+Consider a situation where you are responsible for the high-level software architecture of your project. You define the component breakdown, the interfaces and the interworking of the components. You get your requirements from a system requirement specification, but it turns out many of those incoming requirements are at a detail level that does not require design decisions on inter-component-level but rather affects the internals of a single component.
+
+In those cases it would be a waste of time to repeat the original requirement in your architecture just to hand them down to the detailed design of a component. Instead what you need is a fast way to express "yes, I read that requirement and I am sure it does not need design decisions in the high-level architecture."
+
+To achieve this OFT features a shorthand notation for delegating the job of covering a specification item to one or more different artifact types.
+
+In the following example a requirement in the system requirement specification (artifact type `req`) stated that the web user interface of your product should use the corporate design. This clearly does not require an architectural decision (`arch`), so you forward it directly to the detailed design (`dsn`) level.  
+
+    arch --> dsn : req~web-ui-uses-corporate-design~1
+
 ### Distributing the Detailing Work
 
 In projects of a certain size you always reach the point where a single team is not enough to process the workload. As a consequence is the teams must find a way to distribute the work. A popular approach is splitting the architecture into components that are as independent as possible. Each team is then responsible for one or more distinct components. While the act of assigning the work should never be done inside of the specification, at least the specification can prepare criteria on which to split the work.
@@ -449,4 +461,4 @@ Editor / IDE                                             | Syntax highl. | Previ
 [Eclipse](https://eclipse.org) with WikiText plug-in     | y             | y       | y       | y
 [Eclipse](https://eclipse.org) with GMF plug-in          |               | y       |         |
 [Vim](https://www.vim.org/)                              | y             |         |         |
- 
+[Visual Studio Code](https://code.visualstudio.com/)     | y             | y       | y       |

oft

@@ -0,0 +1,5 @@
+#!/bin/sh
+script_path=$(dirname "$(readlink -f "$0")")
+version=$(grep -zo '<version>.*</ver.*\n.*<name>OpenFastTrace' pom.xml | sed -e's/[^0-9.]//g')
+
+java -jar "$script_path/target/openfasttrace-$version.jar" $@

src/main/java/org/itsallcode/openfasttrace/core/SpecificationItem.java

@@ -28,7 +28,7 @@
 
 import javax.annotation.Generated;
 
-// [impl->dsn~specification-item~2]
+// [impl->dsn~specification-item~3]
 public class SpecificationItem
 {
     private final SpecificationItemId id;
@@ -42,6 +42,7 @@ public class SpecificationItem
     private final List<SpecificationItemId> dependOnIds;
     private final List<String> needsArtifactTypes;
     private final List<String> tags;
+    private final boolean forwards;
 
     private SpecificationItem(final Builder builder)
     {
@@ -57,6 +58,7 @@ private SpecificationItem(final Builder builder)
         this.dependOnIds = builder.dependOnIds;
         this.needsArtifactTypes = builder.neededArtifactTypes;
         this.tags = builder.tags;
+        this.forwards = builder.forwards;
     }
 
     /**
@@ -194,6 +196,15 @@ public List<String> getTags()
         return this.tags;
     }
 
+    /**
+     * @return <code>true</code> if this specification item forwards needed
+     *         coverage
+     */
+    public boolean isForwarding()
+    {
+        return this.forwards;
+    }
+
     @Generated(value = "org.eclipse.Eclipse")
     @Override
     public final int hashCode()
@@ -204,14 +215,15 @@ public final int hashCode()
         result = prime * result + ((this.coveredIds == null) ? 0 : this.coveredIds.hashCode());
         result = prime * result + ((this.dependOnIds == null) ? 0 : this.dependOnIds.hashCode());
         result = prime * result + ((this.description == null) ? 0 : this.description.hashCode());
+        result = prime * result + (this.forwards ? 1231 : 1237);
         result = prime * result + ((this.id == null) ? 0 : this.id.hashCode());
         result = prime * result + ((this.location == null) ? 0 : this.location.hashCode());
         result = prime * result
                 + ((this.needsArtifactTypes == null) ? 0 : this.needsArtifactTypes.hashCode());
-        result = prime * result + ((this.tags == null) ? 0 : this.tags.hashCode());
         result = prime * result + ((this.rationale == null) ? 0 : this.rationale.hashCode());
-        result = prime * result + ((this.title == null) ? 0 : this.title.hashCode());
         result = prime * result + ((this.status == null) ? 0 : this.status.hashCode());
+        result = prime * result + ((this.tags == null) ? 0 : this.tags.hashCode());
+        result = prime * result + ((this.title == null) ? 0 : this.title.hashCode());
         return result;
     }
 
@@ -276,6 +288,10 @@ else if (!this.description.equals(other.description))
         {
             return false;
         }
+        if (this.forwards != other.forwards)
+        {
+            return false;
+        }
         if (this.id == null)
         {
             if (other.id != null)
@@ -309,17 +325,6 @@ else if (!this.needsArtifactTypes.equals(other.needsArtifactTypes))
         {
             return false;
         }
-        if (this.tags == null)
-        {
-            if (other.tags != null)
-            {
-                return false;
-            }
-        }
-        else if (!this.tags.equals(other.tags))
-        {
-            return false;
-        }
         if (this.rationale == null)
         {
             if (other.rationale != null)
@@ -331,25 +336,29 @@ else if (!this.rationale.equals(other.rationale))
         {
             return false;
         }
-        if (this.title == null)
+        if (this.status != other.status)
         {
-            if (other.title != null)
+            return false;
+        }
+        if (this.tags == null)
+        {
+            if (other.tags != null)
             {
                 return false;
             }
         }
-        else if (!this.title.equals(other.title))
+        else if (!this.tags.equals(other.tags))
         {
             return false;
         }
-        if (this.status == null)
+        if (this.title == null)
         {
-            if (other.status != null)
+            if (other.title != null)
             {
                 return false;
             }
         }
-        else if (!this.status.equals(other.status))
+        else if (!this.title.equals(other.title))
         {
             return false;
         }
@@ -372,6 +381,7 @@ public static class Builder
         private final List<SpecificationItemId> dependOnIds;
         private final List<String> neededArtifactTypes;
         private final List<String> tags;
+        private boolean forwards;
 
         /**
          * Create a new instance of type {@link SpecificationItem.Builder}
@@ -616,5 +626,20 @@ public SpecificationItem build()
             }
             return new SpecificationItem(this);
         }
+
+        /**
+         * Set to <code>true</code> if this specification item forwards needed
+         * coverage
+         *
+         * @param forwards
+         *            <code>true</code> if the specification item forwards
+         *            needed coverage
+         * @return this builder instance
+         */
+        public Builder forwards(final boolean forwards)
+        {
+            this.forwards = forwards;
+            return this;
+        }
     }
 }

src/main/java/org/itsallcode/openfasttrace/importer/ImportEventListener.java

@@ -147,4 +147,14 @@ public interface ImportEventListener
      *            the location
      */
     public void setLocation(Location location);
-}
+
+    /**
+     * Set to <code>true</code> if the specification item forwards needed
+     * coverage
+     * 
+     * @param forwards
+     *            <code>true</code> if the specification item forwards needed
+     *            coverage
+     */
+    public void setForwards(boolean forwards);
+}