From 489329f4d2dc7666eda4d8bac0487095fdc441b6 Mon Sep 17 00:00:00 2001
From: Stefan Hynek <stefan.hynek@uni-goettingen.de>
Date: Fri, 22 May 2020 10:40:56 +0200
Subject: [PATCH] style: lint what can be autofixed by markdownlint

this heavily reduces the number of reported errors
---
 rdd-technical-reference.md | 76 +++++++++++++++++---------------------
 1 file changed, 34 insertions(+), 42 deletions(-)

diff --git a/rdd-technical-reference.md b/rdd-technical-reference.md
index 70fd22e..da4cd07 100644
--- a/rdd-technical-reference.md
+++ b/rdd-technical-reference.md
@@ -72,7 +72,6 @@ available as support.
 code style automatically using a code style file. We just collect some advice how to format and use SPARQL code
 [here](https://github.com/subugoe/rdd-technical-reference/tree/master/style-guides/rdd-sparql.md).
 
-
 ## Documentation
 
 ### Doc Sprints
@@ -134,7 +133,6 @@ recommended to use call stacks of tools like Eclipse (Java) and/or Call Graph Mo
 - Document REST-APIs using [openAPI](https://github.com/OAI/OpenAPI-Specification) if possible. OpenAPI docs should be
 located at `/doc/api` on servers.
 
-
 #### CESSDA's Software Maturity Levels in RDD (CA1.3)
 
 ##### MUST
@@ -146,11 +144,11 @@ experienced developer. If available, source code is consistently and clearly com
 are adhered to and consistent.
 
 ##### Actions to Be Taken in RDD
+
 - provide a fully documented public API, e.g. by using OpenAPI
 - naming conventions still have to be discussed --> style guide?
 - reference to style guide used in the CONTRIBUTING/README file?
 
-
 ### Admin Documentation
 
 - The docs should comprise how to install the software, how to run and/or restart it, how to test the installation,
@@ -167,14 +165,13 @@ management and configuration of the software. Exception and failure messages are
 solutions are not available. Documentation is consistent with current version of the software.
 
 ##### Actions to Be Taken in RDD
+
 - deployment: short deployment descriptions can be provided in the README, more detailed explanations should be kept
 separately (such as INSTALL(.md), linked from README)
 - exception and failure messages are described in doc strings/function annotations
 - function documentation should be generated automatically and 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.\
@@ -182,7 +179,6 @@ This type of documentation is provided and maintained in our DARIAH wiki space.\
 We have a template encompassing all information necessary: To create a wiki page for a new server navigate to the FE
 Server list, select "..." right beside the "Create" button and search for "FE-Server".
 
-
 ### User Documentation
 
 This may encompass:
@@ -196,16 +192,17 @@ This may encompass:
 
 - screencasts
 
-
 #### CESSDA's Software Maturity Levels in RDD (CA1.1)
 
 ##### MUST
+
 `MUST` be SML2, which is defined as follows:
 
 > There is external documentation that is accessible and sufficient for an expert user to configure and use the
 software for the user’s individual needs. Terminology and methodology is not explained.
 
 ###### Actions to Be Taken in RDD
+
 - a README(.md) has to be available in the source code repository (cf. [General Notions about
 Documentation](#general-notions-about-documentation))
 
@@ -217,12 +214,11 @@ Documentation](#general-notions-about-documentation))
 user’s individual requirements. Documentation is consistent with current version of the software.
 
 ###### Actions to Be Taken in RDD
+
 - a more detailed explanation is available for the user at some place (such as user guide in wikis, etc. pp.)
 - docs should also be provided in a `docs` directory in the source code repository
 - docs are revised regularly during our doc sprints
 
-
-
 ## Version Control
 
 We exclusively use `git` in RDD. Please see <https://git-scm.com/doc> for information on how it works.
@@ -255,7 +251,6 @@ We use the following Git servers at the moment in RDD:
 - GitLab (GWDG) --> <https://gitlab.gwdg.de>
 - github.org --> <https://github.com/subugoe>
 
-
 Which one is suitable for you depends on:
 
 - the project you are working on
@@ -263,20 +258,15 @@ Which one is suitable for you depends on:
 - whether or not you want to use CI/CD or GitLab Runners
 - ...
 
-
-
 We have got an [RDD team on GitHub](https://github.com/orgs/subugoe/teams/fe). Feel free to join us!
 
-
 Consider mirroring of repos for project visibility (e.g. mirror GitLab/Projects code to GitHub?)
 
-
 ## Bug Tracking
 
 A bug tracking system is obligatory! Please use the respective bug tracking system of your repo and/or project
 management solution (please see chapter [Version Control](#version-control))!
 
-
 ## Software Tests
 
 We aim to have a test coverage of **100%** (except for getter and setter methods). This is understood on a component
@@ -291,7 +281,6 @@ Examples for writing tests in different programming languages are:
 
 - [**XQuery**](https://gist.github.com/joewiz/fa32be80749a69fcb8da)
 
-
 ## Building Code and Continuous Integration
 
 ### Building Code
@@ -305,19 +294,23 @@ out). Another reason is to include dependency management.
 * **bash scripting**: (bdnPrint, FontanePrint)
 * **eXist**: Ant (SADE)
 * **Java**:
+
 - Maven (TextGrid)
 - gradle (TextGrid)
+
 * **JavaScript**:
+
 - bower (DARIAH-DE GeoBrowser, tgForms)
 - cake (tgForms)
 - NPM (DARIAH-DE Publikator, tgForms)
 - rake (DARIAH-DE GeoBrowser)
 
 * **Python**:
+
 - make (Sphinx documentation)
 - PIP (DiscussData)
-* **Ruby**: bundler (DARIAH status page)
 
+* **Ruby**: bundler (DARIAH status page)
 
 ### Packaging
 
@@ -333,11 +326,10 @@ upgraded/rolled back from a Continuous Integration server job (or equivalent). D
 from a Continuous Integration server job (or equivalent).
 
 ###### Actions to Be Taken in RDD
+
 - examples for versions of deployed software: versioning of deb packages
 - examples for rollback: rebuild index ElasticSearch from source data, restore database backup
 
-
-
 ### Continuous Integration
 
 We want to use CI as soon as possible in new projects. Please set up your GitLab project to show your pipeline-status
@@ -346,9 +338,12 @@ 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`
 
@@ -366,7 +361,6 @@ The workflows we are using currently in Jenkins and GitLab Runner are:
 There is a [full and documented example](https://gitlab.gwdg.de/SADE/SADE/blob/develop/.gitlab-ci.yml) of how the
 GitLab Runner is used in SADE.
 
-
 #### Sample Configuration of the Jenkins CI (Multibranch Pipelines)
 
 - On commit and push to the <https://projects.gwdg.de> gitolite repo (such as
@@ -387,7 +381,6 @@ via Maven and a Nexus deploy-account.
 a shared library of scripts and publishing is devided into four conditionals: TG version, DH version, SNAPSHOT version,
 or RELEASE version due to given version suffixes!
 
-
 ## Deployment and Maintenance
 
 ### Puppet
@@ -421,8 +414,6 @@ Telegraf collects statistics with input plugins. A list of plugins is
 
 ### Release Management
 
-
-
 ## Code quality level for RDD
 
 ### Code Reviews
@@ -453,13 +444,11 @@ free to review the code as well. **Note:** MRs without docs should not be accept
 assignee informs the developer over the review being finished.
 6. The developer merges her changes into the development branch.
 
-
-
 ### Proof of Concept
+
 When preparing a proof of concept that is always labeled `poc`, a code review is
 not necessary.
 
-
 ## Intellectual Property
 
 ### Licensing
@@ -493,16 +482,17 @@ intellectual property rights statements are expressed in legal language, machine
 statements in language that can be understood by laypersons, such as a pre-written, recognisable license.
 
 ###### Actions to Be Taken in RDD
+
 - see rdd-technical-reference for choosing the license
-- source code: use OSI approved licenses? (see https://opensource.org/licenses) (++TODO discuss in fe-develop++) (how
+- source code: use OSI approved licenses? (see <https://opensource.org/licenses)> (++TODO discuss in fe-develop++) (how
 to chose a license?:
-http://freesoftwaremagazine.com/articles/choosing_and_using_free_licenses_software_hardware_and_aesthetic_works/fig_choosing_license.jpg)
+<http://freesoftwaremagazine.com/articles/choosing_and_using_free_licenses_software_hardware_and_aesthetic_works/fig_choosing_license.jpg)>
 - assets: CC0? CC-BY-SA? (++TODO discuss in fe-develop++)
 - we reach SML5 by providing a license file on root level containing the license text (GPL wants its license text in a
-file called COPYING [see https://www.gnu.org/licenses/gpl-howto.de.html] other licenses use LICENSE)
+file called COPYING [see <https://www.gnu.org/licenses/gpl-howto.de.html>] other licenses use LICENSE)
 - if the license text is not contained in the license file, we provide the full license text in another file
 (++TODO++)
-(https://softdev4research.github.io/4OSS-lesson/03-use-license/index.html#add-a-licence-file-to-a-repository)
+(<https://softdev4research.github.io/4OSS-lesson/03-use-license/index.html#add-a-licence-file-to-a-repository)>
 - in the source code header the license statement is added to every file. GPL example:
 
 ```
@@ -540,6 +530,7 @@ part of the extension plan, the software is well-structured, has a moderate to h
 configuration elements clearly separated from logic and display elements.“
 
 __Actions to Be Taken in RDD:__
+
 - Future extensibility is designed into the system
 - on RDD developer level
 - source code modification --> software is well-structured
@@ -548,7 +539,6 @@ frameworks
 - configuration elements clearly separated from logic and display elements
 - use SADE as example project
 
-
 ### CA4: Modularity
 
 MUST be __SML3__:
@@ -566,13 +556,13 @@ extensions to program languages for stronger type checking and compilation-time
 externally and code within each module contains few independent logical paths.“
 
 __Actions to Be Taken in RDD:__
+
 - we NEED consistent error handling with meaningful messages and advice
 - if specific errors can occur --> create explicit errors
 - return and input types must be defined if language allows types
 - think of possible reuse of internal methods --> make them externally available
 - one module serves one purpose
 
-
 ### CA6: Portability
 
 (target platform: e.g. Docker container)
@@ -583,12 +573,12 @@ MUST BE __SML5__:
 will run on the target platform provided it is packaged/containerised.“
 
 __Actions to Be Taken in RDD:__
+
 - examples for target platforms: TextGridLab (Windows, Linux, Mac OS), Java Web Services (Web Application Server:
 Tomcat, etcpp), SADE (eXistDB, Linux, Windows), DiscussData-Django-App (jeder Host, für den Docker verfügbar ist)
 
 ++ Michelle möchte, dass wir mehr über Docker sprechen! ++
 
-
 ### CA7: Standards Compliance
 
 MUST BE __SML3__:
@@ -599,67 +589,71 @@ tested but this may not be for all components. There is documented evidence of s
 verification of components.“
 
 __Actions to Be Taken in RDD:__
+
 - coding standards: code style, git (commit hooks), gitflow/gitlabflow, (semantic) versioning
 - software standards: documentation (JavaDoc, OpenAPI, etcpp), data and metadata formats, APIs (REST, SOAP, OAI-PMH,
 etcpp), license
 - CI standards: release workflow (?), deployment
 
-
 ### CA8: Support
 
 MUST BE __SML1__:
 __Actions to Be Taken in RDD:__
+
 - an organizational e-mail-adress must be provided with the readme and in a convenient view, e.g. imprint/help/info
 etc.
 
 SHOULD BE __SML3__:
 __Actions to Be Taken in RDD:__
+
 - provide support "near" the source code (discussable)
 - by any means, provide it in *one* location
 - regular and planned releases
 
-
 ### CA9: Verification and Testing
 
 __Actions to Be Taken in RDD:__
+
 - CESSDAs definitions seems a bit unclear to us
 - without referencing the SMLs we link our test chapter to CESSDAs document
 
-
 ### CA10: Security
 
 MUST BE __SML2__:
 
 __Actions to Be Taken in RDD:__
+
 - every developer must have had a basic security training
 
 SHOULD BE __SML5__:
 
 __Actions to Be Taken in RDD:__
+
 - address security in every step of development (design, implementation, testing and verification, release)
 
 __TODO__:
+
 - mit AL über Training für alle Developer sprechen
 - Anforderungen an Softwaresicherheit formulieren
 - Training erarbeiten (mit Security-Issue-Liste beginnen)
 
-
 ### CA11: Internationalisation and Localisation
 
 MUST BE __SML1,5__
 
 __Actions to Be Taken in RDD:__
+
 - locale awareness is a high requirement for software with a monolingual target audience but you must provide it in
 english (and/or the target language) at least
 
 SHOULD BE __SML3__
 
 __Actions to Be Taken in RDD:__
+
 - if applicable, i18n and l10n frameworks should be used
 
 nice to read:
-https://bridge360blog.com/2011/11/25/software-design-considerations-for-internationalization-and-localization/
-
+<https://bridge360blog.com/2011/11/25/software-design-considerations-for-internationalization-and-localization/>
 
 ### CA12: Authentication and Authorisation
 
@@ -671,16 +665,14 @@ inherently depends on the software's functionality. Instead of developing an own
 possible.
 
 __Actions to Be Taken in RDD:__
+
 - never share passwords
 - use Shibboleth whenever possible and reasonable
 
-
-
 ## Retirement of Software
 
 - clarify if software is no longer supported
 
-
 ## Helpful Links and References
 
 - EURISE-network technical-reference:\
-- 
GitLab