jspaaks / howfairis-github-action

GitHub Action to analyze a GitHub repository’s compliance with the fair-software.eu recommendations.

Assess compliance with fair-software.eu

To enable this checker, add the following snippet as .github/workflows/fair-software.yml in your GitHub repository.

name: fair-software

on: push

jobs:
  verify:
    name: "fair-software"
    runs-on: ubuntu-latest
    steps:
      - uses: fair-software/[email protected]
        name: Measure compliance with fair-software.eu recommendations
        env:
          PYCHARM_HOSTED: "Trick colorama into displaying colored output" 
        with:
          MY_REPO_URL: "https://github.com/${{ github.repository }}"

FAIR badges explained

This GitHub action will suggest a badge visualizing compliance with the FAIR Software recommendations as described on fair-software.eu.

The Netherlands eScience Center and DANS launched fair-software.eu with five actionable and practical recommendations that help researchers to make their software more FAIR (Findable, Accessible, Interoperable, Reusable).

What do we mean by compliance

The GitHub Action does checks on the repository it runs on, and rates the repository according to these 5 aspects:

1. repository: Is the software in a publicly accessible repository with version control?
2. license: Is there a license file? The license does not have to be OSI approved license, but it has to be one of the standard licenses.
3. registry: Is the software registered in one or more software registries? You can find an extensive list of registries in the Awesome Research Software Registries
4. citation: Can the repository be cited easily? For example, this can be done by including a CITATION.cff file, that uses Citation File Format.
5. checklist: Do the developers of the software use a software quality checklist?

Through this GitHub action and the badges that it generates, we want to incentivize Research Software Engineers and researchers who develop software to implement these Five recommendations for FAIR software, by making their effort and compliance with the fair-software.eu recommendations more visible to the rest of the world. We also want to promote the recommendations to a wider audience.

How to interpret FAIR badges?

The color of the badge depends on the level of compliance; the pattern of filled and empty circles will vary depending what aspects the software complies with.

Each circle represents one of the recommendations, meaning the first symbol represents the first recommendation, Use a publicly accessible repository with version control, the second symbol represents the second recommendations, and so on. You can find more information about the recommendations on fair-software.eu.

Here are some examples:

This badge's red color means that the repository complies with 0 or 1 recommendations. The state of the third circle indicates the software has been registered in a community registry.

The repository with this badge complies with 3 out of 5 recommendations, hence its color is orange. It is a publicly accessible repository with version control. It has been registered in a community registry, and it contains citation information. There is no license in this repository, and the project does not use a checklist.

A yellow badge means the repository complies with 4 recommendations.

A green badge means the repository complies with all 5 recommendations.

For developers

Building the docker image:

# (from project root directory)
docker build -t howfairis .

Running the dockerized howfairis locally:

# show howfairis'es help
docker run -ti howfairis --help

# start the analysis for a github repo
docker run -ti howfairis https://github.com/owner/repo

# start the analysis for a gitlab repo
docker run -ti howfairis https://gitlab.com/owner/repo

# show howfairis'es version
docker run -ti howfairis --version