[Feature]: [FRSM-13] Does the software describe what is required to use it?

[karacolada]

D5.2 page 20+29.

Detailed Description

Software is made more reusable by providing suitable machine-actionable information on dependencies, build and configuration.

Generic comments

Most programming languages provide standardised ways of providing dependency information in a machine-actionable format. Build and package management systems can be used to automate the installation process. It is hard to check the relevance / correctness of this information, but it is possible to automatically check for existence and error-free build. Detailed documentation also aids the reusability of software but it is difficult to automatically test for documentation coverage.

CESSDA comments

See Software Maturity Levels (SML) for: CMA1 - Documentation, CMA3 - Extensibility, CM4 - Modularity, CMA5 - Packaging, CMA6 - Portability, and CMA7 - Standards Compliance.

Source code documentation should use the de facto standard for chosen language, e.g: JavaDoc for Java (Manual). Although no language-specific coding conventions are mandated, the ‘Coding conventions for languages’ section of the Wikipedia Coding conventions page is a useful reference source for language-specific guidelines, if required (Software Code Structure guidelines).

Context

R1: Software is described with a plurality of accurate and relevant attributes. R2: Software includes qualified references to other software.

Possible Implementation

requirements	software	status
method	Check for machine-readable information that helps support the understanding of how it is to be used
essential	The software has build, installation and/or execution instructions.	✅
important	Dependencies are provided in a machine-readable format and the building and installation of the software is automated.	✅
useful	N/A

CESSDA

requirements	software	status
method	Check the README file.
essential	Dependency information and build instructions are included in the README file. Linting and other relevant checks are present in the automated build and test process (e.g. via the Jenkinsfile).	✅
important	The README file includes a badge that links to the automated build tool (Jenkins). Deployment to development and staging environments is automated (conditional on test results).	✅
useful	The build badge indicates the status of the latest build (passing or failing)	✅

[karacolada]

Assigned to R1 since the testst don't really align with R2.

[karacolada]

Test general-essential sounds like it's asking for documentation, hence I'm checking README, wiki and a docs/ folder for keywords.

[karacolada]

C1: Linting and other relevant checks are present in the automated build and test process (e.g. via the Jenkinsfile).

Unclear what I'm looking for. How is linting checked in the Jenkinsfile? What are "other relevant checks"? Keywords can be configured in the metrics YAML file though, so can be added by people who know more.

[karacolada]

The difference between the badges in C2 and C3 is unclear to me. I interpreted this as:

• C2 looks for a badge that links to some Jenkins (or other automated tool, used test requirements for keyword search in badge link)
• C3 looks for a badge that uses a job status

Hence, the regexes used are slightly different.

[karacolada]

C3 deployment is difficult to test for - is it mandatory to have multiple environments? If so, that could come in many shapes, so not straightforward to test for. Instead, the test currently just looks for "deploy" in an automated file (again using test requirements for keyword search config).

[karacolada]

List of dependency files: https://github.com/librariesio/bibliothecary/blob/main/README.md

Could also use Bibliothecary, but it's a Ruby Gem. Going through the libraries.io API might be possible, see https://libraries.io/api

[karacolada]

Libraries.io API can list dependencies. We could interpret this as "dependencies are machine-readable"? (https://libraries.io/api)