<!--
SPDX-FileCopyrightText: 2020 Helmholtz Centre Potsdam - GFZ German Research Centre for Geosciences, Germany (https://www.gfz-potsdam.de/)
SPDX-FileCopyrightText: 2021 Helmholtz Centre Potsdam - GFZ German Research Centre for Geosciences, Germany (https://www.gfz-potsdam.de/)

SPDX-License-Identifier: CC0-1.0
-->

# Configuration

Some of the provided services need a configuration.
Here it will be explained which services need a configuration and how it works.
The configuration is separated by service into multiple config files.
You only need a config, if you run the services that need one.

The following services need a configuration:
* Apply license
* Check Credentials
* List used Licenses

The configuration needs to be in a directory in the root of your project.
The directory needs to be named `.sqa`.
All configuration files follow the [yaml](https://yaml.org/) or [toml](https://github.com/toml-lang/toml) format.

---

## Initialize

To generate a initial configuration, run sqa with the `init` command.
If there is already a `.sqa` directory, it will be backed up.
Afterwards the default configuration (and default templates) will be created.

## Apply License

The configuration for this service is mandatory.
Some of the top level entries within the configuration are optional, some are mandatory.

### comment in file

This entry is optional.
By default the header for all files will be generated in a separate `.license` file.
The reuse tool can also generate the header within the files itself.
To determine in which files the header should be within the file, you need to add a [regular expression](https://en.wikipedia.org/wiki/Regular_expression) to a list in this section.
If the reuse tool (which is implemented here) does not know how to add the header to a file, it will generate a '.licene' file.

### description

This entry should be a one liner, that describes the whole software and is mandatory.
It will be added to every file header.

### ignore paths

Optionally you can exclude paths or files from the apply license service.
Its value is a list of [regular expressions](https://en.wikipedia.org/wiki/Regular_expression).
The content of the .gitignore will be automatically ignored.

### licenses

This mandatory entry defines the license for different scopes.
A scope consists of:
* a license, defined by a [spdx-identifier](https://spdx.org/licenses/)
* a copyright owner, represented by a string
* a list of files or paths to apply the scope, defined by [regular expressions](https://en.wikipedia.org/wiki/Regular_expression)

The default scope is the only mandatory scope.
Every file, that is not covered by a non default scope, will get applied the default scope.
That is why the default scope does not have a list of files. 

You can add as many scopes as you want.
If a file falls into multiple non default scopes, the first that matches will will be applied.

```yaml
# OPTIONAL, to determine for which files the license header should be with the file
comment in file:
  - '<PYTHON REGEX>'
# MANDATORY, to add a description of the whole software to the header
description: '<STRING>'
# OPTIONAL, to skip over files for applying the license header
#           usually the things in .gitignore
ignore paths:
  - '<PYTHON REGEX>'
# MANDATORY, to set scopes for multiple licenses in a project
licenses:
  # MANDATORY, all files, that do not go into another scope, go here
  default:
    # MANDATORY, the copyright holder of the file that the header is applied to,
    #            additionally it is used for the entry in the README.md
    copyright: '<STRING>'
    # MANDATORY, unique identifier used for licenses
    spdx-identifier: '<SPDX IDENTIFIER, see https://spdx.org/licenses/>'
  # OPTIONAL, as many scopes as you wish are possible
  #           their names must be unique
  #           the license of the first scope that matches (determined by 'files' below) will be applied
  <SCOPE NAME>:
    # MANDATORY, the copyright holder of the file that the header is applied to
    copyright: '<STRING>'
    # MANDATORY, unique identifier used for licenses
    spdx-identifier: '<SPDX IDENTIFIER, see https://spdx.org/licenses/>'
    # MANDATORY: regex to match to apply this scope
    files:
      - '<PYTHON REGEX>'
```

### example configuration

```yaml
comment in file:
  - '.*.sh$'
  - '.*.py$'
  - '.*.rb$'
  - '.*.yml$'
  - '.*.toml$'
  - '.*.md$'
  - '.*.gitignore$'
  - '.*Dockerfile$'
  - '.*Makefile$'
description: 'This Software provides services to check and improve the source code quality of software-projects'
ignore paths:
  # git
  - '.*.git/.*'
  # IDE's
  - '.*.idea/.*'
  # env
  - '.*venv/.*'
licenses:
  default:
    copyright: 'Helmholtz Centre Potsdam - GFZ German Research Centre for Geosciences, Germany (https://www.gfz-potsdam.de/)'
    spdx-identifier: 'GPL-3.0-or-later'
  Insignificant:
    copyright: 'Helmholtz Centre Potsdam - GFZ German Research Centre for Geosciences, Germany (https://www.gfz-potsdam.de/)'
    spdx-identifier: 'CC0-1.0'
    files:
      - '.*.txt$'
      - '.*.md$'
      - '.*.yml$'
      - '.*Gemfile$'
      - '.*pylintrc$'
      - '.*.testlanguage$'
  Software:
    copyright: 'Helmholtz Centre Potsdam - GFZ German Research Centre for Geosciences, Germany (https://www.gfz-potsdam.de/)'
    spdx-identifier: 'GPL-3.0-or-later'
    files:
      # Python
      - '.*.py$'
      - '.*.py3$'
      # Ruby
      - '.*.rb$'
      # Shell
      - '.*.sh$'
      # Dockerfile
      - '.*Dockerfile*$'
```

## Check Credentials

The service uses the gitleaks configuration.
It is optional.
It is possible to adopt the rules for your needs, by changing the rule set or add exceptions.
Please see the [gitleaks configuration dokumentation](https://github.com/zricethezav/gitleaks/wiki/Configuration) for further information.

## List used Licenses

The configuration for this service is optional.
The top level entries within the configuration are optional.

### exclude

If you want to exclude some files or directories from the license check, you can do that here.
Some things should be included, like documentation or tests.
To exclude something you need to add a [regular expression](https://en.wikipedia.org/wiki/Regular_expression) to a list in this section.
The content of the .gitignore will be automatically ignored.

### manual dependency config

Sometimes dependencies have to be managed manually for sqa.
It is a list of dependencies - separated by programming language.
Here are cases listed, when you should do that:

#### naming inconsistency

> **Note:** (always needed for other cases)

It is possible that the name to download a library differs from the import name.
An example is PyYAML.
You download it via `pip install PyYAML` but import it with `import yaml`.
This matching need to be done manually.

In the 'manual dependency config' section add a new key, representing the programming language of the dependency.
Withing this there is a list containing multiple key:value pairs.
Fill in at least 'import name' and 'pkg name'.
Both entries can be identical.

#### ignore libraries

If you import parts of your own repository (e.g. a module of your software), there is no way of retrieving the license of it.
we need to exclude them.
To do that, follow the steps for [naming inconsistency](#naming-inconsistency).
Then add the key 'ignore' to the dependency you want to ignore.
You can skip this key instead of setting it to 'False'.

#### missing license information

Sometime package repositories do not know the license(s) of a package.
You can set them manually, if you know better (e.g. by checking the source code).
To do that, follow the steps for [naming inconsistency](#naming-inconsistency).
Then add the key 'licenses' to the dependency you want to set the license(s) manually.
The value of 'licenses' is a list of valid [spdx-identifiers](https://spdx.org/licenses/).

### empty configuration

```yaml
# OPTIONAL, files, paths to exclude from analyzing licenses
#           non-programming language files should go here
exclude:
  - '<PYTHON REGEX>'
manual dependency config:
  # MANDATORY, the name of the programming language the library is used in
  <NAME OF PROGRAMMING LANGUAGE>:
      # MANDATORY, sometimes the name to import differs from the name to download via a pkg-manager
      #            therefore the matching can be done here, if it cannot be resolved by a pkg manager
    - import name: '<IMPORT NAME>'
      pkg name: '<DOWNLOAD NAME>'
      # OPTIONAL, if the dependency is a local import (part of your software) you should ignore it,
      #           because is has no license
      ignore: '<BOOLEAN>'
      # OPTIONAL, it is possible to use two different versions of a dependency - you can set the version here
      version: '<VERSION STRING>'
      # OPTIONAL, it is common, that the pkg repositories do not know the license(s) for a package
      #           you can give assign it here
      licenses:
        - '<SPDX-IDENTIFIER>'
```

### example configuration

```yaml
exclude:
  - 'docs/.*' # documentation
  - '.*.gitlab-ci.yml$' # ci files
  - 'meta/.*' # meta data
  - 'test/.*' # test files
  - '.*dep5_template$' # plain text template file, not source code
manual dependency config:
  Python:
    - import name: 'functions'
      pkg name: 'functions'
      ignore: True
    - import name: 'yaml'
      pkg name: 'PyYAML'
    - import name: 'stdlib_list'
      pkg name: 'stdlib-list'
    - import name: 'igittigitt'
      pkg name: 'igittigitt'
      licenses:
        - 'MIT'
```