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
Branches
Tags
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.
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:\
......
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Please register or to comment