Skip to content
Snippets Groups Projects
Commit 489329f4 authored by Stefan Hynek's avatar Stefan Hynek :drooling_face:
Browse files

style: lint what can be autofixed by markdownlint 

this heavily reduces the number of reported errors
parent 2a2fb42e
No related branches found
No related tags found
1 merge request!22Resolve "move to gitlab and Automize pdfenize markdown document"
Pipeline #136341 passed with warnings
Stage: test
Hide whitespace changes
Inline Side-by-side
rdd-technical-reference.md
+ 34
− 42
View file @ 489329f4
...@@ -72,7 +72,6 @@ available as support. ...@@ -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 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). [here](https://github.com/subugoe/rdd-technical-reference/tree/master/style-guides/rdd-sparql.md).
## Documentation ## Documentation
### Doc Sprints ### Doc Sprints
...@@ -134,7 +133,6 @@ recommended to use call stacks of tools like Eclipse (Java) and/or Call Graph Mo ...@@ -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 - Document REST-APIs using [openAPI](https://github.com/OAI/OpenAPI-Specification) if possible. OpenAPI docs should be
located at `/doc/api` on servers. located at `/doc/api` on servers.
#### CESSDA's Software Maturity Levels in RDD (CA1.3) #### CESSDA's Software Maturity Levels in RDD (CA1.3)
##### MUST ##### MUST
...@@ -146,11 +144,11 @@ experienced developer. If available, source code is consistently and clearly com ...@@ -146,11 +144,11 @@ experienced developer. If available, source code is consistently and clearly com
are adhered to and consistent. are adhered to and consistent.
##### Actions to Be Taken in RDD ##### Actions to Be Taken in RDD
- provide a fully documented public API, e.g. by using OpenAPI - provide a fully documented public API, e.g. by using OpenAPI
- naming conventions still have to be discussed --> style guide? - naming conventions still have to be discussed --> style guide?
- reference to style guide used in the CONTRIBUTING/README file? - reference to style guide used in the CONTRIBUTING/README file?
### Admin Documentation ### Admin Documentation
- The docs should comprise how to install the software, how to run and/or restart it, how to test the installation, - 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 ...@@ -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. solutions are not available. Documentation is consistent with current version of the software.
##### Actions to Be Taken in RDD ##### Actions to Be Taken in RDD
- deployment: short deployment descriptions can be provided in the README, more detailed explanations should be kept - deployment: short deployment descriptions can be provided in the README, more detailed explanations should be kept
separately (such as INSTALL(.md), linked from README) separately (such as INSTALL(.md), linked from README)
- exception and failure messages are described in doc strings/function annotations - 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 - function documentation should be generated automatically and made available/searchable in the web (such as
readthedocs, javadoc html, etc. pp.) readthedocs, javadoc html, etc. pp.)
### Server Documentation ### Server Documentation
This type of documentation is provided and maintained in our DARIAH wiki space.\ 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.\ ...@@ -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 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". Server list, select "..." right beside the "Create" button and search for "FE-Server".
### User Documentation ### User Documentation
This may encompass: This may encompass:
...@@ -196,16 +192,17 @@ This may encompass: ...@@ -196,16 +192,17 @@ This may encompass:
- screencasts - screencasts
#### CESSDA's Software Maturity Levels in RDD (CA1.1) #### CESSDA's Software Maturity Levels in RDD (CA1.1)
##### MUST ##### MUST
`MUST` be SML2, which is defined as follows: `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 > 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. software for the user’s individual needs. Terminology and methodology is not explained.
###### Actions to Be Taken in RDD ###### Actions to Be Taken in RDD
- a README(.md) has to be available in the source code repository (cf. [General Notions about - a README(.md) has to be available in the source code repository (cf. [General Notions about
Documentation](#general-notions-about-documentation)) Documentation](#general-notions-about-documentation))
...@@ -217,12 +214,11 @@ 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. user’s individual requirements. Documentation is consistent with current version of the software.
###### Actions to Be Taken in RDD ###### 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.) - 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 should also be provided in a `docs` directory in the source code repository
- docs are revised regularly during our doc sprints - docs are revised regularly during our doc sprints
## Version Control ## Version Control
We exclusively use `git` in RDD. Please see <https://git-scm.com/doc> for information on how it works. 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: ...@@ -255,7 +251,6 @@ We use the following Git servers at the moment in RDD:
- GitLab (GWDG) --> <https://gitlab.gwdg.de> - GitLab (GWDG) --> <https://gitlab.gwdg.de>
- github.org --> <https://github.com/subugoe> - github.org --> <https://github.com/subugoe>
Which one is suitable for you depends on: Which one is suitable for you depends on:
- the project you are working on - the project you are working on
...@@ -263,20 +258,15 @@ Which one is suitable for you depends 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 - 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! 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?) Consider mirroring of repos for project visibility (e.g. mirror GitLab/Projects code to GitHub?)
## Bug Tracking ## Bug Tracking
A bug tracking system is obligatory! Please use the respective bug tracking system of your repo and/or project 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))! management solution (please see chapter [Version Control](#version-control))!
## Software Tests ## Software Tests
We aim to have a test coverage of **100%** (except for getter and setter methods). This is understood on a component 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: ...@@ -291,7 +281,6 @@ Examples for writing tests in different programming languages are:
- [**XQuery**](https://gist.github.com/joewiz/fa32be80749a69fcb8da) - [**XQuery**](https://gist.github.com/joewiz/fa32be80749a69fcb8da)
## Building Code and Continuous Integration ## Building Code and Continuous Integration
### Building Code ### Building Code
...@@ -305,19 +294,23 @@ out). Another reason is to include dependency management. ...@@ -305,19 +294,23 @@ out). Another reason is to include dependency management.
* **bash scripting**: (bdnPrint, FontanePrint) * **bash scripting**: (bdnPrint, FontanePrint)
* **eXist**: Ant (SADE) * **eXist**: Ant (SADE)
* **Java**: * **Java**:
- Maven (TextGrid) - Maven (TextGrid)
- gradle (TextGrid) - gradle (TextGrid)
* **JavaScript**: * **JavaScript**:
- bower (DARIAH-DE GeoBrowser, tgForms) - bower (DARIAH-DE GeoBrowser, tgForms)
- cake (tgForms) - cake (tgForms)
- NPM (DARIAH-DE Publikator, tgForms) - NPM (DARIAH-DE Publikator, tgForms)
- rake (DARIAH-DE GeoBrowser) - rake (DARIAH-DE GeoBrowser)
* **Python**: * **Python**:
- make (Sphinx documentation) - make (Sphinx documentation)
- PIP (DiscussData) - PIP (DiscussData)
* **Ruby**: bundler (DARIAH status page)
* **Ruby**: bundler (DARIAH status page)
### Packaging ### Packaging
...@@ -333,11 +326,10 @@ upgraded/rolled back from a Continuous Integration server job (or equivalent). D ...@@ -333,11 +326,10 @@ upgraded/rolled back from a Continuous Integration server job (or equivalent). D
from a Continuous Integration server job (or equivalent). from a Continuous Integration server job (or equivalent).
###### Actions to Be Taken in RDD ###### Actions to Be Taken in RDD
- examples for versions of deployed software: versioning of deb packages - examples for versions of deployed software: versioning of deb packages
- examples for rollback: rebuild index ElasticSearch from source data, restore database backup - examples for rollback: rebuild index ElasticSearch from source data, restore database backup
### Continuous Integration ### 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 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. ...@@ -346,9 +338,12 @@ and test-coverage for your default-branch under Settings/General->Badges.
The generic links for all projects are: The generic links for all projects are:
* Pipeline-status * Pipeline-status
- Link: `https://gitlab.gwdg.de/%{project_path}/commits/%{default_branch}` - 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` - Badge image URL: `https://gitlab.gwdg.de/%{project_path}/badges/%{default_branch}/pipeline.svg?style=flat-square`
* Test-coverage * Test-coverage
- Link: `https://gitlab.gwdg.de/%{project_path}/commits/%{default_branch}` - 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` - 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: ...@@ -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 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. GitLab Runner is used in SADE.
#### Sample Configuration of the Jenkins CI (Multibranch Pipelines) #### Sample Configuration of the Jenkins CI (Multibranch Pipelines)
- On commit and push to the <https://projects.gwdg.de> gitolite repo (such as - 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. ...@@ -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, 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! or RELEASE version due to given version suffixes!
## Deployment and Maintenance ## Deployment and Maintenance
### Puppet ### Puppet
...@@ -421,8 +414,6 @@ Telegraf collects statistics with input plugins. A list of plugins is ...@@ -421,8 +414,6 @@ Telegraf collects statistics with input plugins. A list of plugins is
### Release Management ### Release Management
## Code quality level for RDD ## Code quality level for RDD
### Code Reviews ### Code Reviews
...@@ -453,13 +444,11 @@ free to review the code as well. **Note:** MRs without docs should not be accept ...@@ -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. assignee informs the developer over the review being finished.
6. The developer merges her changes into the development branch. 6. The developer merges her changes into the development branch.
### Proof of Concept ### Proof of Concept
When preparing a proof of concept that is always labeled `poc`, a code review is When preparing a proof of concept that is always labeled `poc`, a code review is
not necessary. not necessary.
## Intellectual Property ## Intellectual Property
### Licensing ### Licensing
...@@ -493,16 +482,17 @@ intellectual property rights statements are expressed in legal language, machine ...@@ -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. statements in language that can be understood by laypersons, such as a pre-written, recognisable license.
###### Actions to Be Taken in RDD ###### Actions to Be Taken in RDD
- see rdd-technical-reference for choosing the license - 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?: 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++) - 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 - 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 - if the license text is not contained in the license file, we provide the full license text in another file
(++TODO++) (++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: - 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 ...@@ -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.“ configuration elements clearly separated from logic and display elements.“
__Actions to Be Taken in RDD:__ __Actions to Be Taken in RDD:__
- Future extensibility is designed into the system - Future extensibility is designed into the system
- on RDD developer level - on RDD developer level
- source code modification --> software is well-structured - source code modification --> software is well-structured
...@@ -548,7 +539,6 @@ frameworks ...@@ -548,7 +539,6 @@ frameworks
- configuration elements clearly separated from logic and display elements - configuration elements clearly separated from logic and display elements
- use SADE as example project - use SADE as example project
### CA4: Modularity ### CA4: Modularity
MUST be __SML3__: MUST be __SML3__:
...@@ -566,13 +556,13 @@ extensions to program languages for stronger type checking and compilation-time ...@@ -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.“ externally and code within each module contains few independent logical paths.“
__Actions to Be Taken in RDD:__ __Actions to Be Taken in RDD:__
- we NEED consistent error handling with meaningful messages and advice - we NEED consistent error handling with meaningful messages and advice
- if specific errors can occur --> create explicit errors - if specific errors can occur --> create explicit errors
- return and input types must be defined if language allows types - return and input types must be defined if language allows types
- think of possible reuse of internal methods --> make them externally available - think of possible reuse of internal methods --> make them externally available
- one module serves one purpose - one module serves one purpose
### CA6: Portability ### CA6: Portability
(target platform: e.g. Docker container) (target platform: e.g. Docker container)
...@@ -583,12 +573,12 @@ MUST BE __SML5__: ...@@ -583,12 +573,12 @@ MUST BE __SML5__:
will run on the target platform provided it is packaged/containerised.“ will run on the target platform provided it is packaged/containerised.“
__Actions to Be Taken in RDD:__ __Actions to Be Taken in RDD:__
- examples for target platforms: TextGridLab (Windows, Linux, Mac OS), Java Web Services (Web Application Server: - 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) 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! ++ ++ Michelle möchte, dass wir mehr über Docker sprechen! ++
### CA7: Standards Compliance ### CA7: Standards Compliance
MUST BE __SML3__: MUST BE __SML3__:
...@@ -599,67 +589,71 @@ tested but this may not be for all components. There is documented evidence of s ...@@ -599,67 +589,71 @@ tested but this may not be for all components. There is documented evidence of s
verification of components.“ verification of components.“
__Actions to Be Taken in RDD:__ __Actions to Be Taken in RDD:__
- coding standards: code style, git (commit hooks), gitflow/gitlabflow, (semantic) versioning - 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, - software standards: documentation (JavaDoc, OpenAPI, etcpp), data and metadata formats, APIs (REST, SOAP, OAI-PMH,
etcpp), license etcpp), license
- CI standards: release workflow (?), deployment - CI standards: release workflow (?), deployment
### CA8: Support ### CA8: Support
MUST BE __SML1__: MUST BE __SML1__:
__Actions to Be Taken in RDD:__ __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 - an organizational e-mail-adress must be provided with the readme and in a convenient view, e.g. imprint/help/info
etc. etc.
SHOULD BE __SML3__: SHOULD BE __SML3__:
__Actions to Be Taken in RDD:__ __Actions to Be Taken in RDD:__
- provide support "near" the source code (discussable) - provide support "near" the source code (discussable)
- by any means, provide it in *one* location - by any means, provide it in *one* location
- regular and planned releases - regular and planned releases
### CA9: Verification and Testing ### CA9: Verification and Testing
__Actions to Be Taken in RDD:__ __Actions to Be Taken in RDD:__
- CESSDAs definitions seems a bit unclear to us - CESSDAs definitions seems a bit unclear to us
- without referencing the SMLs we link our test chapter to CESSDAs document - without referencing the SMLs we link our test chapter to CESSDAs document
### CA10: Security ### CA10: Security
MUST BE __SML2__: MUST BE __SML2__:
__Actions to Be Taken in RDD:__ __Actions to Be Taken in RDD:__
- every developer must have had a basic security training - every developer must have had a basic security training
SHOULD BE __SML5__: SHOULD BE __SML5__:
__Actions to Be Taken in RDD:__ __Actions to Be Taken in RDD:__
- address security in every step of development (design, implementation, testing and verification, release) - address security in every step of development (design, implementation, testing and verification, release)
__TODO__: __TODO__:
- mit AL über Training für alle Developer sprechen - mit AL über Training für alle Developer sprechen
- Anforderungen an Softwaresicherheit formulieren - Anforderungen an Softwaresicherheit formulieren
- Training erarbeiten (mit Security-Issue-Liste beginnen) - Training erarbeiten (mit Security-Issue-Liste beginnen)
### CA11: Internationalisation and Localisation ### CA11: Internationalisation and Localisation
MUST BE __SML1,5__ MUST BE __SML1,5__
__Actions to Be Taken in RDD:__ __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 - 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 english (and/or the target language) at least
SHOULD BE __SML3__ SHOULD BE __SML3__
__Actions to Be Taken in RDD:__ __Actions to Be Taken in RDD:__
- if applicable, i18n and l10n frameworks should be used - if applicable, i18n and l10n frameworks should be used
nice to read: 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 ### CA12: Authentication and Authorisation
...@@ -671,16 +665,14 @@ inherently depends on the software's functionality. Instead of developing an own ...@@ -671,16 +665,14 @@ inherently depends on the software's functionality. Instead of developing an own
possible. possible.
__Actions to Be Taken in RDD:__ __Actions to Be Taken in RDD:__
- never share passwords - never share passwords
- use Shibboleth whenever possible and reasonable - use Shibboleth whenever possible and reasonable
## Retirement of Software ## Retirement of Software
- clarify if software is no longer supported - clarify if software is no longer supported
## Helpful Links and References ## Helpful Links and References
- EURISE-network technical-reference:\ - EURISE-network technical-reference:\
......
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment