Merge branch '130-final-editing' into 'main'

Resolve "Final editing"

Closes #130

See merge request !101

chapters/development/bug-tracking.md

@@ -7,5 +7,5 @@ A bug tracking system `MUST` be used.
 
 #### Guidelines
 
-Please use the respective bug tracking system of your repo and/or project
-management solution (see chapter [Version Control](#version-control))!
+Use the respective bug tracking system of your repo and/or project
+management solution (see chapter [Version Control](#version-control)).

chapters/development/build.md

@@ -9,22 +9,16 @@ This allows for building and/or testing a project with one command and facilitat
 - **bash scripting**: (bdnPrint, FontanePrint)
 - **eXist**: Ant (SADE)
 - **Java**:
-
-- Maven (TextGrid)
-- gradle (TextGrid)
-
+  - Maven (TextGrid)
+  - gradle (TextGrid)
 - **JavaScript**:
-
-- bower (DARIAH-DE GeoBrowser, tgForms)
-- cake (tgForms)
-- NPM (DARIAH-DE Publikator, tgForms)
-- rake (DARIAH-DE GeoBrowser)
-
+  - bower (DARIAH-DE GeoBrowser, tgForms)
+  - cake (tgForms)
+  - NPM (DARIAH-DE Publikator, tgForms)
+  - rake (DARIAH-DE GeoBrowser)
 - **Python**:
-
-- make (Sphinx documentation)
-- PIP (DiscussData)
-
+  - make (Sphinx documentation)
+  - PIP (DiscussData)
 - **Ruby**: bundler (DARIAH status page)
 
 #### Packaging and Dependency Management
@@ -32,7 +26,7 @@ This allows for building and/or testing a project with one command and facilitat
 In general, code packages can be installed as site packages (system-wide) or into the app directory
 (known as "vendoring" or "bundling") through a packaging system.
 
-Your app `SHOULD NOT` depend on system-wide packages. You `SHOULD` declare all dependencies
+Your app `SHOULD` `NOT` depend on system-wide packages. You `SHOULD` declare all dependencies
 of your app in a
 dependency declaration manifest and ensure that
 there are no leaks from the surrounding system ("package isolation").
@@ -41,7 +35,7 @@ For example, in Python, package isolation can be ensured by using a
 virtual environment (`virtualenv`/`venv`).
 A `requirements.txt` configuration file can be used to list required packages
 (and their supported version or range of versions)
-and can be installed using `pip install -r requirements.txt`.
+and can be installed using `pip` `install` `-r` `requirements.txt`.
 This allows users to quickly set up everything they need to run the app.
 
 Dependencies are resolved in a transitive manner,

chapters/development/design-architecture.md

@@ -43,5 +43,5 @@ If a web service is shipped in a container it `MUST` provide a port where it is
 reachable via the HTTP protocol. The container may ship an Apache HTTP Server
 or the application may declare a library for serving HTTP as a dependency.
 
-The container `MUST NOT` provide SSL encryption,
-as this is the job of a frontend server.
+The container `MUST` `NOT` provide SSL encryption,
+as this is the job of a front end server.

chapters/development/documentation.md

@@ -85,8 +85,8 @@ Call diagrams can be useful to follow code and service calls and should exist fo
 ###### API Documentation
 
 - Provide a fully documented public API, e.g. by using OpenAPI
-- The docs `SHOULD` comprise `used parameters`, `author` and `@since` annotations
-- Links to callers `MUST NOT` be listed in the documentation, because this info might become deprecated at any time
+- The docs `SHOULD` comprise `used` `parameters`, `author` and `@since` annotations
+- Links to callers `MUST` `NOT` be listed in the documentation, because this info might become deprecated at any time
 - REST-APIs `SHOULD` be documented by using [OpenAPI](https://github.com/OAI/OpenAPI-Specification).
 
 The OpenAPI documentation `SHOULD` be located at `/doc/api` on servers.
@@ -133,10 +133,6 @@ as done [here](https://sphinxcontrib-openapi.readthedocs.io)).
 - Function documentation should be generated automatically
 - Function documentation should be made available/searchable in the web (such as readthedocs, javadoc html, etc. pp.)
 
-##### Server Documentation
-
-This type of documentation is provided and maintained in our DARIAH wiki space (currently read-only).
-
 ##### User Documentation
 
 This may encompass:
@@ -148,7 +144,7 @@ This may encompass:
 - screencasts
 
 - A README(.md) `MUST` be available in the source code repository (cf. [General Notions about Documentation](#general-notions-about-documentation))
-- A more detailed explanation `SHOULD`be available for the user at some place (such as user guide in wikis, etc. pp.)
+- A more detailed explanation `SHOULD` be available for the user at some place (such as user guide in wikis, etc. pp.)
 - Docs `SHOULD` be provided in a `docs` directory in the source code repository
 - Docs `SHOULD` revised regularly (e.g. during doc sprints)
 

chapters/development/logging.md

@@ -7,7 +7,7 @@
 
 The application is responsible for providing a stream of meaningful log messages.
 
- It `MUST NOT` determine the output destination of the log stream (e.g. write it into a log file).
+ It `MUST` `NOT` determine the output destination of the log stream (e.g. write it into a log file).
  This will be handled by the environment in which the application is run.
  Instead, the application simply writes the logs to `stdout`.
  When run locally for development, the logs may be viewed directly in the terminal,
@@ -33,7 +33,7 @@ Chose an appropriate log level and adhere to the **most common**, depending on t
 - **ERROR**
 - FATAL/CRITICAL
 
-Log messages `MUST NOT` contain any sensitive data (access keys, passwords, personal data, ...).
+Log messages `MUST` `NOT` contain any sensitive data (access keys, passwords, personal data, ...).
 If it is necessary to log these information for debugging reasons, the log level `MUST` be "DEBUG" (or lower).
 A properly configured logagent will filter out all logs of level "DEBUG" (or lower) on production environments.
 

chapters/development/software-tests.md

 
 ### Software Tests
 
+#### Policy
+
 Software tests aim at ensuring that the code you write does exactly what you expect it to do.
 
 All functions (except `get`ter and `set`ter methods) `MUST` provide proper tests.

chapters/development/version-control.md

@@ -47,7 +47,7 @@ This avoids accidental pushes to these branches.
 
 All specific branches working on an issue described in a bug tracker `SHOULD` utilize the following naming scheme:
 \
-`ISSUENUMBER-DESCRIPTION`\
+`ISSUE_NUMBER-DESCRIPTION`\
 \
 
 e.g. `12-flux-capacitor`.

chapters/introduction/about.md

@@ -17,5 +17,5 @@ discussed, worked out, and decided on by the Software Quality Working Group.
 agreed on a new standard for software projects in the SUB's Research and Development Department.
 TODOs and addenda to this document are maintained at this project's [issue tracker](https://gitlab.gwdg.de/fe/technical-reference/issues/).
 
-**Terminology**: The key words `MUST`, `MUST NOT`, `REQUIRED`, `SHALL`, `SHALL NOT`, `SHOULD`, `SHOULD NOT`,
+**Terminology**: The key words `MUST`, `MUST` `NOT`, `REQUIRED`, `SHALL`, `SHALL NOT`, `SHOULD`, `SHOULD` `NOT`,
 `RECOMMENDED`, `MAY`, and `OPTIONAL` in this document are to be interpreted as described in [RFC 2119](https://tools.ietf.org/html/rfc2119).

chapters/operation/maintenance.md

@@ -28,8 +28,8 @@ regular processes, in the interest of dependency isolation.
 
 Logging is neither centralized nor enforced (yet) and you have to provide a proper configuration for the logging agent yourself.
 [General recommendations](https://www.loggly.com/ultimate-guide/managing-linux-logs/) apply.
-An agent `MUST NOT` log at "DEBUG" level or beyond (e.g. "TRACE", "SILLY") in production environments to prevent
-[PII](https://www.pokewiki.de/Pii) or [other sensible data](https://en.wikipedia.org/wiki/Personal_data#European_Union)
+An agent `MUST` `NOT` log at "DEBUG" level or beyond (e.g. "TRACE", "SILLY") in production environments to prevent
+personal identifiable information or [other sensible data](https://en.wikipedia.org/wiki/Personal_data#European_Union)
 to be aggregated. This means, configure the agent for level "INFO" or above if there is no level between "DEBUG" and "INFO".
 
 ##### Icinga

chapters/security/ci-cd.md

@@ -13,19 +13,7 @@ Due to the separation of the three stages, code
 cannot be changed at runtime.
 
 We `RECOMMEND` using CI as soon as possible in new projects. Please set up your GitLab project to show your pipeline status
-and test-coverage for your default branch under Settings/General->Badges.
-
-The generic links for all projects are:
-
-- Pipeline-status
-
-- Link: `https://gitlab.gwdg.de/%{project_path}/commits/%{default_branch}`
-- Badge image URL: `https://gitlab.gwdg.de/%{project_path}/badges/%{default_branch}/pipeline.svg?style=flat-square`
-
-- Test-coverage
-
-- Link: `https://gitlab.gwdg.de/%{project_path}/commits/%{default_branch}`
-- Badge image URL: `https://gitlab.gwdg.de/%{project_path}/badges/%{default_branch}/coverage.svg?style=flat-square`
+and test-coverage for your default branch under "Settings / General → Badges".
 
 The workflows we are currently using in the GitLab Runner are:
 

chapters/security/code-quality.md

 
-### Code quality
+### Code Quality
 
 #### Code Reviews
 
@@ -14,13 +14,13 @@ only developer, should work cross-team.
    issue, and a merge request (MR). The MR has draft status by default. (This step matches the GitLab Flow.)
 1. Checkout the branch locally and start implementing.
 1. Commit and push your changes.
-1. Remove the draft status of the MR if the changes meet the issue objective. You `MUST` assign and contact at least one
-   suitable reviewer.
-1. The reviewers must examine the changes regarding the fulfillments of the issue, coding language, understandability,
+1. Remove the draft status of the MR if the changes meet the issue objective.
+   You `MUST` assign and contact one suitable reviewer.
+1. The reviewer must examine the changes regarding the fulfillments of the issue, coding language, understandability,
    documentation. The reviewers suggest improvements or approve the MR.
 1. The developer merges the branch if the review was successful.
 
-#### Code quality measurement with Gitlab-CI
+#### Code Quality Measurement with GitLab-CI
 
 GitLab-CE provides some tools which can be used
 [to measure code quality](https://docs.gitlab.com/ee/user/project/merge_requests/code_quality.html).

chapters/security/release-management.md

@@ -18,8 +18,8 @@ To enforce Conventional Commits with your project, we recommend to use Commitize
 preferably the [commitizen adapter for the angular preset](https://github.com/commitizen/cz-conventional-changelog).
 
 If you use GitLab for hosting your source code, you can also add a **push rule** to your group or repository.
-Go to "Push Rules" on group level or select "Settings > Repository > Push Rules" in your project to enter a regex that
-prohibits all contributors to push commit or branches with names that don't comply to your rule.
+Go to "Push Rules" on group level or select "Settings / Repository → Push Rules" in your project to enter a
+regex that prohibits all contributors to push commit or branches with names that don't comply to your rule.
 
 #### Semantic Versioning and Semantic Release
 
@@ -29,4 +29,4 @@ periods.
 
 Doing a release with Semantic Versioning is often called a Semantic Release.
 You `SHOULD` automate all steps in the process of a Semantic Release.
-To help with the creation of a changelog, release notes and a gitlab release, use the npm tool [semantic-release](https://semantic-release.gitbook.io/semantic-release/).
+To help with the creation of a changelog, release notes and a GitLab release, use the npm tool [semantic-release](https://semantic-release.gitbook.io/semantic-release/).

chapters/security/sbom.md

@@ -6,6 +6,10 @@ This also includes the components' licenses as well as their versions.
 The aims of a SBOM are to increase transparency of the software supply chain and to easily detect security risks and
 quality defects in dependencies.
 
+#### Policy
+
+Every repository contains a regularly updated SBOM file that is uploaded to SUB's instance of [Dependency Track](#using-dependency-track).
+
 #### SBOM Creation and Tooling
 
 There are a lot of tools available for conveniently creating SBOMs for your codebase.
@@ -18,9 +22,6 @@ In RDD, we currently recommend using the following:
 - **NodeJS**: [cdxgen](https://github.com/AppThreat/cdxgen) >= 4.0.19
 - **Container images**: [syft](https://github.com/anchore/syft)
 
-Your project's SBOM `MUST` be updated regularly, e.g. as part of your CI/CD workflow, and be uploaded to a central
-inventory (see [Using Dependency Track](#using-dependency-track)).
-
 #### Using Dependency Track
 
 To fully utilize your project's SBOM, it shouldn't just be part of your repository but put to further use.
@@ -40,7 +41,8 @@ See also the following two templates for GitLab CI that might come in handy:
 
 ```yaml
 include:
-  - remote: https://gitlab.gwdg.de/dariah-de/gitlab-templates/-/raw/main/templates/.deps.gitlab-ci.yml
+  - remote: https://gitlab.gwdg.de/dariah-de/gitlab-templates/-/raw/main/
+    templates/.deps.gitlab-ci.yml
 
 upload-container-sbom:
   stage: deploy
@@ -66,5 +68,6 @@ and takes care of the rest:
 
 ```yaml
 include:
-  - remote: https://gitlab.gwdg.de/dariah-de/gitlab-templates/-/raw/main/templates/SBOM-Upload.gitlab-ci.yml
+  - remote: https://gitlab.gwdg.de/dariah-de/gitlab-templates/-/raw/main/
+    templates/SBOM-Upload.gitlab-ci.yml
 ```