Merge pull request #599 from dedica-team/develop

Release 0.4.0

.github/ISSUE_TEMPLATE/dev_intro.md

@@ -0,0 +1,14 @@
+---
+name: Introduction to nivio development
+about: How to get started
+title: ''
+labels: ''
+assignees: ''
+
+---
+
+- [ ] follow the instructions here: https://github.com/dedica-team/nivio/blob/develop/development.md and get a self-built nivio instance running
+- [ ] for backend development, get familiar with the Spring Boot framework: https://spring.io/guides/gs/spring-boot/
+- [ ] for frontend development, get familiar with React https://reactjs.org/docs/getting-started.html and Material UI https://material-ui.com/
+
+There is a public Slack dedica-extern.slack.com for chat support.

.github/workflows/ci.yml

@@ -25,10 +25,10 @@ jobs:
       - name: Install dependencies and check format
         run: yarn && yarn format:check
         working-directory: ./src/main/app
+
   test:
     runs-on: ${{matrix.os}}
     strategy:
-      max-parallel: 1
       matrix:
         os: [macos-latest, ubuntu-latest, windows-latest]
         jdk: [11.0.8, 13.0.2]
@@ -63,3 +63,46 @@ jobs:
         # Reference: https://maven.apache.org/ref/3.6.3/maven-embedder/cli.html
         # This is useful as the tests run in fresh containers and, therefore, dependencies are *always* downloaded.
         run: mvn test --batch-mode --no-transfer-progress --f pom.xml
+
+  scan:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v2
+        with:
+          fetch-depth: 2
+
+      - name: Set up JDK 11
+        uses: actions/setup-java@v1
+        with:
+          java-version: 11.0.8
+
+      - name: Cache SonarCloud packages
+        uses: actions/cache@v1
+        with:
+          path: ~/.sonar/cache
+          key: ${{ runner.os }}-sonar
+          restore-keys: ${{ runner.os }}-sonar
+
+      - name: Cache local Maven repository
+        uses: actions/cache@v2
+        with:
+          path: ~/.m2/repository
+          key: ${{runner.os}}-maven-${{hashFiles('**/pom.xml')}}
+          restore-keys: ${{runner.os}}-maven-
+
+      - name: Get yarn cache directory path
+        id: yarn-cache-dir-path
+        run: echo "::set-output name=dir::$(yarn cache dir)"
+
+      - name: Cache local Yarn repository
+        uses: actions/cache@v2
+        with:
+          path: ${{steps.yarn-cache-dir-path.outputs.dir}}
+          key: ${{runner.os}}-yarn-${{hashFiles('**/yarn.lock')}}
+          restore-keys: ${{runner.os}}-yarn-
+
+      - name: Scan with Sonar
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}  # Needed to get PR information, if any
+          SONAR_TOKEN: ${{ secrets.SONAR_TOKEN }}
+        run: mvn package --batch-mode --no-transfer-progress --f pom.xml org.sonarsource.scanner.maven:sonar-maven-plugin:sonar

.github/workflows/epics.yml

@@ -0,0 +1,15 @@
+name: Update epics
+on:
+  issues:
+    types: [opened, closed, reopened]
+jobs:
+  epics:
+    runs-on: ubuntu-latest
+    name: Update epic issues
+    steps:
+      - name: Run epics action
+        uses: cloudaper/epics-action@v1
+        with:
+          github-token: ${{ secrets.GITHUB_TOKEN }}
+          epic-label-name: epic
+          auto-close-epic: false

.github/workflows/main.yml

@@ -7,7 +7,6 @@ on:
     branches:
       - master
       - develop
-      - 107_deploy_heroku
 
 jobs:
 
@@ -19,8 +18,17 @@ jobs:
       uses: actions/setup-java@v1
       with:
         java-version: 11.0.4
+    - name: Cache SonarCloud packages
+      uses: actions/cache@v1
+      with:
+        path: ~/.sonar/cache
+        key: ${{ runner.os }}-sonar
+        restore-keys: ${{ runner.os }}-sonar
     - name: Build with Maven
-      run: mvn package -B --file pom.xml
+      env:
+        GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}  # Needed to get PR information, if any
+        SONAR_TOKEN: ${{ secrets.SONAR_TOKEN }}
+      run: mvn package -B --no-transfer-progress --file pom.xml org.sonarsource.scanner.maven:sonar-maven-plugin:sonar
 
     #
     # docker
@@ -52,4 +60,4 @@ jobs:
         docker push registry.heroku.com/nivio-demo/web
         heroku container:release web -a nivio-demo
       env:
-        HEROKU_API_KEY: ${{ secrets.HEROKU_API_KEY }}
+        HEROKU_API_KEY: ${{ secrets.HEROKU_API_KEY }}

.gitignore

@@ -9,3 +9,4 @@ src/test/resources/example/*_debug.png
 src/test/resources/example/*_debug.json
 src/test/resources/example/*_debug.svg
 src/main/resources/static/icons/svg/*.svg
+/src/main/app/debug.log

CONTRIBUTING.md

@@ -1,6 +1,6 @@
 # How to contribute
 
-We are really glad you're reading this, because we need volunteer developers to help this project come to fruition.
+We are really glad you're reading this because we need volunteer developers to help this project come to fruition.
 
 If you haven't already, come find us on [Slack](https://dedica-hacktoberfest.slack.com/). We want you working on things you're excited about.
 
@@ -10,7 +10,7 @@ Here are some important resources:
   * [Our project roadmap](https://github.com/dedica-team/nivio/projects/1)
   * [Issues](https://github.com/dedica-team/nivio/issues)
   * [Chat](https://dedica-hacktoberfest.slack.com/)
-  * *Readme* both frontend and backend contain readme files (see ./src/main/...)
+  * *Readme* - both frontend and backend contain readme files (see ./src/main/...)
 
 ## Testing
 
@@ -23,7 +23,7 @@ Please send a [GitHub Pull Request](https://github.com/opengovernment/opengovern
 
   * The *develop* branch is the base for all new features.
   * Always write a clear log message for your commits.
-  * Please include the ticket id in commit messages, if possible.
+  * Please include the ticket id in commit messages if possible.
   * Make sure that your contribution is well tested.
   * Try not to introduce new dependencies for common tasks
 
@@ -32,9 +32,9 @@ Please send a [GitHub Pull Request](https://github.com/opengovernment/opengovern
 Start reading our code and you'll get the hang of it. We optimize for readability:
 
   * We think that the Zen Of Python is a good idea and we hate code generation.
-  * In Java we indent using four spaces (Intellij default settings)
+  * In Java we indent using four spaces (IntelliJ default settings)
   * In React we indent using two spaces using prettier.
-  * This is open source software. Consider the people who will read your code, and make it look nice for them. 
+  * This is open source software. Consider the people who will read your code and make it look nice for them. 
 
 Thanks,
 the dedica team

development.md

@@ -0,0 +1,80 @@
+# Getting Started with Nivio Development
+
+
+**Requirements**
+
+To run nivio you need the following software installed:
+- [nodejs v12.6.2 or higher](https://nodejs.org/en/), [How to update node?](https://www.hostingadvice.com/how-to/update-node-js-latest-version/)
+- [Maven](https://maven.apache.org/install.html)
+- Java 11
+
+---
+
+**Docker Setup (Linux)**
+
+Clone nivio, build and run a Docker image:
+
+    git clone https://github.com/dedica-team/nivio.git && cd nivio
+    mvn clean package
+    docker build -t nivio:latest .
+    docker run -e SEED=/tmp/nivio/inout.yml --mount type=bind,source="$(pwd)"/src/test/resources/example,target=/tmp/nivio -p 8080:8080 nivio:latest
+
+  then open http://localhost:8080
+
+**Docker Setup (Windows)**
+
+  Clone nivio, build and run a Docker image:
+
+      git clone https://github.com/dedica-team/nivio.git && cd nivio
+      mvn clean package
+      docker build -t nivio:latest .
+      docker run -e SEED=//tmp/nivio/inout.yml --mount type=bind,source="C:\<your>\<path>\<to>\nivio\src\test\resources\example",target=/tmp/nivio -p 8080:8080 nivio:latest
+      
+   then open http://localhost:8080
+
+   (Note: the double slashes at the beginning of the path for the SEED environment variable work as a fix to make MSYS/MinGW consoles
+   *not* translate the `/tmp` path to a local DOS path. This is safe to use with the PowerShell. Further reading: https://stackoverflow.com/a/14189687/10000398)
+
+   ---
+
+**Development Setup (IntelliJ)**
+
+ Create a Spring Boot Configuration in IntelliJ that looks like this:
+
+  ![Spring Boot Config](https://raw.githubusercontent.com/dedica-team/nivio/develop/docs/SpringConfig.png)
+
+  If you need a clean build you can run 
+
+    mvn clean package
+
+  You can use your own configuration files, if you add SEED=/path/to/config as an environment variable.
+
+  Open http://localhost:8080
+
+  If you want to contribute to our frontend, read further into our [Frontend Readme](https://github.com/dedica-team/nivio/tree/develop/src/main/app)
+
+**Nivio Backend Architecture**
+
+If you want to contribute to our backend, maybe the following diagram is of use to you. It shows some of the most important classes and 
+interfaces. It is supposed to give you an idea on how the backend is structured, but note that not all details are displayed:
+
+ ![layoutedArtifact graph](backend_architecture_api.png)
+
+ If you use the `ApiController` as the entry point to the backend, you can see that it retrieves information and triggers events
+  to the most important parts of the application. 
+
+The `LandscapeRespository` gives access to the stored landscapes.
+
+The `LandscapeDescriptionFactory` is used to generate a `LandscapeDescription` from various sources, such as a `String` input, 
+or e.g. from a yaml file. 
+
+This `LandscapeDescription` has to be enriched with the `ItemDescription` for all items in the landscape.
+This is managed by the `InputFormatHandler`, which are able to read several input formats such as e.g. kubernetes files, or the
+nivio description format. Access to these handlers is managed by the `InputFormatHandlerFactory`.
+
+To actually create a landscape, the `Indexer` is used. This is able to compute the landscape graph from a `LandscapeDescription`.
+The `Indexer` uses several `Resolver` to resolve groups and item relations in landscapes and e.g. the appearance of the graph.
+
+The `Indexer` can be triggered either directly through the `ApiController` to index or reindex a landscape, or it is triggered
+by an observer mechanism on files. These are the files located under the path provided through the `SEED` environment variable.
+

docs/k8s-minikube.md

@@ -1,6 +1,6 @@
 # Nivio Minikube
 
-The complete instruction can be found at https://docs.bitnami.com/kubernetes/get-started-kubernetes/
+The complete instructions can be found at https://docs.bitnami.com/kubernetes/get-started-kubernetes/
 
 
 ## Install (on Ubuntu Linux)
@@ -50,4 +50,4 @@ kubectl describe secret dashboard-admin-sa-token-*****
 ## Start nivio
 ```
 SEED=$(pwd)./src/test/resources/example/example_k8s.yml java -jar target/nivio.jar
-``` 
+``` 

docs/source/assessment.rst

@@ -1,7 +1,7 @@
 Data Assessment using KPIs
 ==========================
 
-KPIs (Key Performance Indicator) can be used to evaluate landscape components (typically items, but also groups) based on
+:abbr:`KPIs (Key Performance Indicators)` can be used to evaluate landscape components (typically items, but also groups) based on
 their properties. The result is a status represented by colors (ordinal):
 
 * UNKNOWN (order 0): status could not be determined
@@ -15,25 +15,52 @@ their properties. The result is a status represented by colors (ordinal):
 Built in KPIs
 -------------
 
-* scaling (warning is the scale label is exactly 0)
-* * red if 0 as provider for other items
-* * yellow if scaled to 0 without relations
-* * orange of scaled to 0 as data sink
-* * unknown if no label or not a number
-* * green if scaled higher than 1
-* * yellow if a bottleneck (more than 1 item depend on it)
+Scaling
+^^^^^^^
+This KPI evaluates the scale label and tries to find bottlenecks where providers for many items are down or not scaled.
+
+* red if 0 as provider for other items
+* yellow if scaled to 0 without relations
+* orange of scaled to 0 as data sink
+* unknown if no label or not a number
+* green if scaled higher than 1
+* yellow if a bottleneck (more than 1 item depends on it)
+
+Lifecycle
+^^^^^^^^^
+This KPI evaluates the lifecycle label for "official" values.
+
+* PRODUCTION turns the KPI value to GREEN
+* END_OF_LIFE turns it to ORANGE
+
+Other
+^^^^^
+
 * health (examines the health label on items)
 * condition (K8s condition true/false evaluation)
-* custom (see below)
 
-By default all shipped KPIs are enabled. To disable them, set "enabled" to false in the config.
+By default all shipped `KPIs (Key Performance Indicators)` are enabled. Set ``enabled`` to false in the config to disable them.
+
+.. code-block:: yaml
+   :linenos:
+
+    identifier: kpi_example
+
+    config:
+      kpis:
+        scaling:
+          enabled: false
+
 
 Custom KPIs
 -----------
 
 Custom KPIs can be configured in the landscape config using ranges and/or matchers (regular expressions) and applied to everything having labels.
-In the example below a KPI "monthlyCosts" is defined using ranges on the label "costs" and the KPI "myEval" evaluates a
-label "foo". Both ranges (inclusive lower and upper limits) and matchers are separated by semicolon.
+In the example below a KPI ``monthlyCosts`` is defined, using ranges on the label ``costs``, and the KPI ``myEval`` evaluates a
+label ``foo``.
+
+* Both ranges (inclusive lower and upper limits) and matchers are separated by semicolon.
+* The displayed message can be customized by a template. The placeholder for the value is '%s'.
 
 .. code-block:: yaml
    :linenos:
@@ -46,6 +73,7 @@ label "foo". Both ranges (inclusive lower and upper limits) and matchers are sep
         monthlyCosts:
           description: Evaluates the monthly maintenance costs
           label: costs
+          messageTemplate: "Monthly costs: $%s"
           ranges:
             GREEN: 0;99.999999
             YELLOW: 100;199.999999
@@ -59,5 +87,3 @@ label "foo". Both ranges (inclusive lower and upper limits) and matchers are sep
             RED: "BAD;err.*"
         health:
           description: can be overridden
-        scaling:
-          enabled: false