Merge pull request #173 from itsallcode/develop

2.0.0

.travis.yml

@@ -16,11 +16,13 @@ cache:
 
 before_script:
   - pip install --user codecov
+  - version=$(grep -oP '(?<=^    <version>)[^<]*' pom.xml)
 
 before_install:
   - echo -n | openssl s_client -connect scan.coverity.com:443 | sed -ne '/-BEGIN CERTIFICATE-/,/-END CERTIFICATE-/p' | sudo tee -a /etc/ssl/certs/ca-
 
 script:
+  - echo "Parsed the version $version from pom.xml" 
   - mvn clean org.jacoco:jacoco-maven-plugin:prepare-agent install
 
 after_success:
@@ -30,7 +32,7 @@ addons:
   coverity_scan:
     project:
       name: itsallcode/openfasttrace
-      version: 0.5.4
+      version: $version
       description: OpenFastTrace requirement tracing
     notification_email: [email protected]
     build_command_prepend: mvn clean

CONTRIBUTING.md

@@ -1,7 +1,7 @@
 Thank you for your interest in helping us to make OpenFastTrace (OFT) better!
 
 # Goal of This Document
-This document aims at answering all the questions potential contributers to OFT might have before feeling ready to get started.
+This document aims at answering all the questions potential contributors to OFT might have before feeling ready to get started.
 
 # What This Document is not
 If you are looking for general information about what OpenFastTrace is, please make sure to check out the [ReadMe](./README.md) that comes with the project.

README.md

@@ -1,17 +1,22 @@
 # <img src="src/main/resources/openfasttrace_logo.svg" alt="OFT logo" width="150"/> OpenFastTrace
 
+## What is OpenFastTrace?
+
+OpenFastTrace is a requirement tracing suite. Requirement tracing helps you keeping track of whether you actually implemented everything you planned to in your specifications. It also identifies obsolete parts of your product and helps you getting rid of them.
+
+You can learn more about requirement tracing and how to use OpenFastTrace in the [user guide](doc/user_guide.md).
+
+## Project Information
+
 [![Build Status](https://travis-ci.org/itsallcode/openfasttrace.svg)](https://travis-ci.org/itsallcode/openfasttrace)
 [![Circle CI](https://circleci.com/gh/itsallcode/openfasttrace.svg?style=svg)](https://circleci.com/gh/itsallcode/openfasttrace)
 [![codecov](https://codecov.io/gh/itsallcode/openfasttrace/branch/develop/graph/badge.svg)](https://codecov.io/gh/itsallcode/openfasttrace)
 [![Coverity Scan Build Status](https://scan.coverity.com/projects/14936/badge.svg)](https://scan.coverity.com/projects/itsallcode-openfasttrace)
 [![Download](https://api.bintray.com/packages/itsallcode/itsallcode/openfasttrace/images/download.svg)](https://bintray.com/itsallcode/itsallcode/openfasttrace/_latestVersion)
+[![Maven Central](https://img.shields.io/maven-central/v/org.itsallcode/openfasttrace.svg?label=Maven%20Central)](http://search.maven.org/#search%7Cga%7C1%7Cg%3A%22org.itsallcode%22%20a%3A%22openfasttrace%22)
 
 Sonarcloud status:
 
-## Installation
-
-### Dependencies
-
 [![Quality Gate](https://sonarcloud.io/api/project_badges/measure?project=org.itsallcode%3Aopenfasttrace%3Adevelop&metric=alert_status)](https://sonarcloud.io/dashboard?id=org.itsallcode%3Aopenfasttrace%3Adevelop)
 [![Bugs](https://sonarcloud.io/api/project_badges/measure?project=org.itsallcode%3Aopenfasttrace%3Adevelop&metric=bugs)](https://sonarcloud.io/dashboard?id=org.itsallcode%3Aopenfasttrace%3Adevelop)
 [![Code smells](https://sonarcloud.io/api/project_badges/measure?project=org.itsallcode%3Aopenfasttrace%3Adevelop&metric=code_smells)](https://sonarcloud.io/dashboard?id=org.itsallcode%3Aopenfasttrace%3Adevelop)
@@ -24,21 +29,47 @@ Sonarcloud status:
 [![Technical Dept](https://sonarcloud.io/api/project_badges/measure?project=org.itsallcode%3Aopenfasttrace%3Adevelop&metric=sqale_index)](https://sonarcloud.io/dashboard?id=org.itsallcode%3Aopenfasttrace%3Adevelop)
 [![Vulnerabilities](https://sonarcloud.io/api/project_badges/measure?project=org.itsallcode%3Aopenfasttrace%3Adevelop&metric=vulnerabilities)](https://sonarcloud.io/dashboard?id=org.itsallcode%3Aopenfasttrace%3Adevelop)
 
-## Project Information
+* [Blog](https://blog.itsallcode.org/)
+* [Contributing guide](CONTRIBUTING.md)
+* [OpenFastTrace stories](https://github.com/itsallcode/openfasttrace/wiki/OFT-Stories)
+* [User Guide](doc/user_guide.md)
+* [Command Line Usage](doc/usage.txt)
+* [Design](doc/design.md)
+* [System Requirements](doc/system_requirements.md)
 
+## Download
 
-* ![Contributing guide](CONTRIBUTING.md)
-* ![OpenFastTrace stories](https://github.com/itsallcode/openfasttrace/wiki/OFT-Stories)
-* ![Command Line Usage](doc/usage.txt)
-* ![Design](doc/design.md)
-* ![System Requirements](doc/system_requirements.md)
+Download the executable jar at [jcenter](https://jcenter.bintray.com/org/itsallcode/openfasttrace/):
 
+* [openfasttrace-1.2.1.jar](https://jcenter.bintray.com/org/itsallcode/openfasttrace/1.2.1/openfasttrace-1.2.1.jar)
 
-### On Linux
+### Maven
 
-#### Ubuntu or Debian
+To use OpenFastTrace as a dependency in your maven project add this to your `pom.xml`:
 
-    apt-get install openjdk-8-jre
+```xml
+<dependencies>
+    <dependency>
+        <groupId>org.itsallcode</groupId>
+        <artifactId>openfasttrace</artifactId>
+        <version>1.2.1</version>
+        <scope>compile</scope>
+    </dependency>
+</dependencies>
+```
+
+### Gradle
+
+To use OpenFastTrace as a dependency in your gradle project:
+
+```groovy
+repositories {
+    jcenter()
+}
+dependencies {
+    compile "org.itsallcode:openfasttrace:1.2.1"
+}
+```
 
 ## Using OpenFastTrace
 
@@ -50,9 +81,9 @@ Check the [user guide](doc/user_guide.md) for information on how to use OpenFast
 
 OpenFastTrace only needs a Java 8 (or later) runtime environment to run.
 
-### Installation on Linux
+#### Installation of runtime dependencies on Linux
 
-#### Ubuntu or Debian
+##### Ubuntu or Debian
 
 If you just want to run OFT:
 
@@ -62,7 +93,6 @@ If you want to build OFT:
 
     apt-get install openjdk-8-jdk maven
 
-
 ## Development
 
 ### Build Time Dependencies
@@ -139,14 +169,17 @@ mvn -DwithHistory org.pitest:pitest-maven:mutationCoverage
     </servers>
     ```
 
-2. Update version in `pom.xml`, commit and push.
-3. Run command
+1. Checkout the `develop` branch.
+1. Update version in `pom.xml` and `README.md`, commit and push.
+1. Run command
 
     ```bash
     mvn deploy
     ```
 
-4. Create a [release](https://github.com/itsallcode/openfasttrace/releases) on GitHub.
-5. Sign in at [bintray.com](https://bintray.com)
-6. Go to the [bintray project page](https://bintray.com/itsallcode/itsallcode/openfasttrace)
-7. There should be a notice saying "You have 6 unpublished item(s) for this package". Click the "Publish" link.
+1. Create a [release](https://github.com/itsallcode/openfasttrace/releases) on GitHub.
+1. Sign in at [bintray.com](https://bintray.com)
+1. Go to the [bintray project page](https://bintray.com/itsallcode/itsallcode/openfasttrace)
+1. There should be a notice saying "You have 6 unpublished item(s) for this package". Click the "Publish" link. Binaries will be available for download at [jcenter](https://jcenter.bintray.com/org/itsallcode/openfasttrace/)
+1. Publish to Maven Central by clicking the "Sync" button at https://bintray.com/itsallcode/itsallcode/openfasttrace#central. After some time the new version will appear at https://repo1.maven.org/maven2/org/itsallcode/openfasttrace/.
+

doc/design.md

@@ -1,7 +1,12 @@
 <head><link href="oft_spec.css" rel="stylesheet"></link></head>
 
 # Introduction
-This document is derived from the "[arc42][bib.arc42]" architectural template.
+
+## Acknowledgements
+
+This documents structure is derived from the "[arc42][bib.arc42]" architectural template by Dr. Gernot Starke, Dr. Peter Hruschka.
+
+If you build your own modifications based on this document, please keep the attrbiutions.
 
 ## Terminology
 The terminology from the [system requirement specification][bib.srs] applies.
@@ -140,14 +145,25 @@ Covers:
 
 Needs: impl, utest, itest
 
-#### Filtering by Tags Import
+#### Filtering by Tags During Import
 `dsn~filtering-by-tags-during-import~1`
 
-When OFT is configured to restrict inclusion to tags the [specification list builder](#specification-list-builder) imports a specification item only if at least one of it tags is contained in the configured set of tags.
+The [specification list builder](#specification-list-builder) can be configured to import a specification item only if at least one of its tags is contained in the configured set of tags.
 
 Covers:
 
-* `req~include-only-tags~1`
+* `req~include-items-where-at-least-on-tag-matches~1`
+
+Needs: impl, utest, itest
+
+#### Filtering by Tags or no Tags During Import
+`dsn~filtering-by-tags-or-no-tags-during-import~1`
+
+The [specification list builder](#specification-list-builder) can be configured to import a specification item only if it either has no tags or at least one of its tags is contained in the configured set of tags.
+
+Covers:
+
+* `req~include-items-that-do-not-have-tags-or-where-at-least-one-tag-matches~1`
 
 Needs: impl, utest, itest
 
@@ -311,6 +327,51 @@ Covers:
 
 Needs: impl, utest
 
+#### Plain Text Report Contains Specification Item Origin
+`dsn~reporting.plain-text.specification-item-origin~1`
+
+If enabled, the plain text report shows the origin of a specification item
+
+* for files: `<absolute path to file>:<line number>`
+
+Rationale:
+
+This format is recognized by most IDEs and automatically turned into a link in the IDE's console.
+
+Covers:
+
+* `req~reporting.requirement-origin~1`
+
+#### Plain Text Report Link Contains Specification Item Origin
+`dsn~reporting.plain-text.linked-specification-item-origin~1`
+
+If enabled, the links in the plain text report show the origin of a specification item
+
+* for files: `<absolute path to file>:<line number>`
+
+Rationale:
+
+This format is recognized by most IDEs and automatically turned into a link in the IDE's console.
+
+Covers:
+
+* `req~reporting.requirement-origin~1`
+
+Needs: impl, utest, itest
+
+### HTML Report
+
+#### HTML Report Inlines CSS
+`dsn~reporting.html.inline_css~1`
+
+OFT inlines the cascading style sheet (CSS) into the HTML report.
+
+Covers:
+
+* `req~reporting.html.single_file~1`
+
+Needs: impl, itest
+
 ## Requirement Format Conversion
 
 ### ReqM2 Export
@@ -327,6 +388,26 @@ Covers:
 
 Needs: impl, itest
 
+#### HTML Report Contains Specification Item Origin
+`dsn~reporting.html.specification-item-origin~1`
+
+If enabled, the HTML report shows the origin of a specification item as an HTML link pointing to the source.
+
+Covers:
+
+* `req~reporting.requirement-origin~1`
+
+#### HTML Report Link Contains Specification Item Origin
+`dsn~reporting.html.linked-specification-item-origin~1`
+
+If enabled, the links in the plain text report show the origin of a specification item as an HTML link pointing to the source.
+
+Covers:
+
+* `req~reporting.requirement-origin~1`
+
+Needs: impl, utest, itest
+
 # Deployment View
 
 # Concepts

doc/system_requirements.md

@@ -130,6 +130,17 @@ This can be read directly as console output or with any text editor.
 
 Needs: req
 
+#### HTML Report
+`feat~html-report~1`
+
+OFT produces a tracing report in Hypertext markup language (HTML).
+
+Rationale:
+
+This report type is more optically appealing than the plain text report and still widely supported on all platforms.
+
+Needs: req
+
 ### User Interface
 
 #### Command Line Interface
@@ -414,10 +425,21 @@ Covers:
 
 Needs: dsn
 
-#### Include Only Tags
-`req~include-only-tags~1`
+#### Include Items Where at Least One Tag Matches
+`req~include-items-where-at-least-on-tag-matches~1`
 
-OFT gives users the option to include only specification items contained in configurable set of tags during processing.
+OFT gives users the option to include only specification items that have at least one tag from a configurable set of tags during processing.
+
+Covers:
+
+* [feat~requirement-tracing~1](#requirement-tracing)
+
+Needs: dsn
+
+#### Include Items That Don't Have Tags Or Where at Least One Tag Matches 
+`req~include-items-that-do-not-have-tags-or-where-at-least-one-tag-matches~1`
+
+OFT gives users the option to include only specification items that either do not have tags or have at least one tag from a configurable set of tags during processing.
 
 Covers:
 
@@ -430,6 +452,25 @@ Reports are the main way to find out if a projects requirements are covered prop
 
 #### Common Report Functions
 
+##### Requirement Origin in Report
+`req~reporting.requirement-origin~1`
+
+Users can choose to display the requirement origin (e.g. file and line number) in reports:
+
+* In the body of a specification item
+* For each link to a specification item 
+
+Rationale:
+
+This is especially useful for debugging since it makes finding broken sources faster.
+
+Covers:
+
+* [feat~plain-text-report~1](#plain-text-report)
+* [feat~html-report~1](#html-report)
+
+Needs: dsn
+
 #### Plain Text Report
 The plain text report is the most basic report variant. It serves two main purposes:
 
@@ -487,6 +528,23 @@ Covers:
 
 Needs: dsn
 
+#### HTML Report
+
+##### HTML Report is a Single File
+`req~reporting.html.single_file~1`
+
+OFT creates the HTML Report as a single file.
+
+Rationale:
+
+It makes exchanging reports with other people easier if everything is contained in a single file.  
+
+Covers:
+
+* [feat~html-report~1](#html-report)
+
+Needs: dsn
+
 ### Requirement Format Conversion
 OFT supports conversion from one requirement format into another for example from Markdown to ReqM2.
 

doc/usage.txt

@@ -16,14 +16,20 @@ Tracing options:
 Converting options:
   -o, --output-format format   Requirements format, one of "specobject"
                                Defaults to "specobject"
+  -s, --show-origin            Show the origin of specification items
+                               (e.g. file and line number)             
 
 Common options: 
   -f, --file path              The output file. Defaults to STDOUT.
   -i, --ignore-artifact-types  Define a comma-separated list of artifact types
                                to be ignored during import.
   -n, --newline format         Newline format one of "unix", "windows", "oldmac"
-  -a, --wanted-artifact-types  Filter out all but the artifact types in the
+  -a, --wanted-artifact-types  Import only specification items contained in the
                                comma-separated list
+  -t, --wanted-tags            Import only specification items that have at
+                               least one tag contained in the comma-separated
+                               list. Add a single underscore as first item in
+                               the list to also import items without any tags.
 
 Returns:
   0   on success