Github
MavenQuality: From Principles to Realizations
This section provides general principles of quality and derives processes and decisions on tools realizing these principles to a wide extent.
The core are the General Thoughts. Therein we mention in which sense these thoughts are realized.
General Thoughts
At the time of this writing, at simuline there was a software developed but not maintained for a long span of time and so also quality management did not keep pace with advances in development technologies. In particular, new compiler and quality management tools became stricter. So we must distinguish between what is desirable in future and what is mandatory now.
The core development is in java solely. This uniformity is important because of the tense resources of the company. In general, it is a principle to keep the set of technologies and tools small and uniform. Also, tools used must be kept in a small range and tools must be open source and free.
Besides, hardware and installation must be uniform.
What applies to hardware and installation also applies to configuration.
Beyond this, mainstream is preferred to special configuration.
Thus, we use en_US locale internally;
only for communication with customers and other stakeholders,
we may switch to another language if the customer desires to do so.
Another promienent aspect for uniformity is editing. We use a single mainstream editor, VS Code, with Emacs as a fallback. This is used for coding of any language and to write the documentation in any format. Moreover it supports development with various kinds of checkers. All this is only possible by use of extensions. So installation for editing facilities is installation of the editor and of its extensions. The same principle applies to Emacs, but it needs more manual work, one of the reasons for preferring VS Code. The mandatory extensions are those installed.
Documentation is done with latex, Markdown and jupyter notebooks only and also the form of documentation is quite restricted.
Related with estimation of uniformity is the focus on automation.
In particular, for installation scripts are preferred over manual procedures.
Also in quality management, the first step is running a linting tool,
prior to manual review.
This applies both to code check and to documentation.
Before manual review, code is automaticaly checked and injection
is the technique the artifact tied to this project realizes uniform automatted checks.
Documentation may be split into API-documentation of code, and in textual documentation.
Whereas for java code the first one is covered by the maven-javadoc-plugin,
the latter is more compliated and thus treated separately.
As far as possible, processes shall be automated. Automation also helps to keep up reproducibility. Important are processes which help to be productive and to reach good quality.
Textual documentation
Textual documentation is in latex and in Markdown. Note that latex and markdown overlap in formulae. Jupyter notebook is a separate format but in part it is markdown, in part it is just code, so that there are just two proper formats.
Both formats are written using VS Code with according extensions.
These comprise ltex which can lint both, latex and Markdown.
For latex, latex-maven-plugin is used to transform into any needed output format.
Besides textual documentation, there is also code documentation,
above all for java.
Also, code is written with VS Code and for java the extension redhat.java is used.
This supports online linting and formatting.
Linting LaTeX and Markdown with ltex
There is a code checker for latex and for Markdown
at the same time, ltex.
Its documentation
shows, among other things, how to treat documents with mixed language.
Essentially, one has to write in general on documentation, then elaborate which is specific for the languages under use.
Linting and Formatting Java Online
VS Code is used with extension redhat.java which includes linting and formatting also.
The configuration can be done locally, but also via internet.
We use the latter way to obtain uniformity across the projects
and to minimize installation overhead.
We are aware that there are also drawbacks as e.g. a lot of work when changing the ruleset.
The ruleset
is derived from the according config used by google.
It is accessible on the site via
site.
The same configurations are also used by maven plugins.
LaTeX or markdown
Ideally, there is a single documentation system but LaTeX and markdown offer unique advantages the other does not offer. While LaTeX moves slowly, markdown develops quickly and so additional abilities must be taken into account.
At time of this writing, the following distinctive features are present. For features of LaTeX, the tool or the package or the class in the LaTeX universe realizing the feature is given
| Feature | LaTeX | markdown | |
|---|---|---|---|
| Math formulae | (lua)latex |
? | |
| bibliography | bibtex |
? | |
| index | makeindex |
? | |
| glossary | makeglossaries |
? | |
| executable | pythontex |
- | |
| raster pics | (lua)latex |
yes | |
| fig | (lua)latex |
? | |
| gnuplot | (lua)latex |
? | |
| metapost | (lua)latex |
? | |
| svg | (lua)latex |
? |
LaTeX not only offers glossaries and bibliographies, it offers access to terminology and literature management.
Combining LaTeX and markdown
As already pointed out, ltex is a linter for both LaTeX and markdown.
Also, https://plantuml.com/latex shows some way of integration of PlantUML
which is included in Markdown.
Some problem is that markdown does not support inclusion of markdown files.
I shall suggest the syntax .
From LaTeX side, there is a markdown package.
Check links and usage
To keep up consistency, links are vital.
There is a maven plugin to check links of a site, maven-linkcheck-plugin,
but is not usable.
Thus, the plan is to write such a plugin.
It shall follow links in HTML files and in PDF files.
Whereas HTML files are easily parsed,
for PDF files pdfinfo is used.
- All outgoing links of
xxx.pdfare given bypdfinfo -url xxx.pdf. - For ingoing links of
xxx.pdf, either the file itself is referenced or a so called ‘destination’. All destinations are given bypdfinfo -dests xxx.pdf. One must distinguish:- Linking is not easy for files not created by this company, because no conventions apply.
- Self-made files are created with LaTeX
with
hyperrefpackage and optiondestlabeland so the destinations names are those of the according labels.
It is also important, to track whether all files in a site are reachable by links starting with the central index file. If not a warning shall be given.
Writing rules applying in general
All aspects mentioned so far may be checked automatically, but there are also writing rules for which there are no checks and even writing rules which require human judgement.
Most of the material is applicable independent of markup language, i.e. latex or Markdown, also independent of content language.
This is collected in a separate document.