Rules

Basics

  • everything in this repository is free software.

  • the reported software versions are valid at the moment of writing

Structure

  • scripts and systemd unit files are placed in different directories according to categories.

  • if files are imported into a script, these will be classified as configuration files

  • scripts cannot run without configuration files

  • scripts or systemd unit files are optional:

    • a standalone systemd unit file does the job in some cases. In this case configuration files are not needed

    • a script does not necessarly need a systemd unit file

File naming

Configuration and systemd unit files follow naming schemes that make easier to relate multiple services to configurations and multiple configurations to scripts.

Variables

Variable

Configuration file name word separator

Systemd unit file name word separator

script_name

_

-

subject

_

_

  • optional variables and constants are reported between square brackets ([ and ])

Script

Configuration

Systemd unit file

${script_name}.{py,sh}

${script_name}.[${subject}.]{conf,options}

${script_name}.[${subject}.]{service,timer}

Scripts page

Variables

Variable name

Description

${script_name}

the name of the script

${category_name}

the name of the category that identifies the directory where the source file have been placed

${running_user}

see the List of runing users section in the references page

${path_i}

the path of a file

Schema

Important

Since commit 8852e61 the metadata file is generated dynamically using the YAML data sections of the scripts documentation.

Important

Optional elements must be omitted if empty.

The following schema represents a single entry translated into HTML.

 1<h3>${script_name}</h3>                             # required
 2<img src="assets/image/${script_name}_${i}">        # i = 0->n
 3<h4>Purpose</h4>                                    # required
 4<p></p>                                             # required
 5<h4>Examples</h4>
 6<p></p>
 7<h4>Steps</h4>                                      # an implicit step for all the scripts is to edit the configuration file{,s}
 8<ol>
 9    <li></li>                                       # 1->n
10</ol>
11<h4>References</h4>
12<ul>
13    <li></li>                                       # 1->n
14</ul>
15<h4>Programming languages</h4>                      # required
16<ul>                                                # required
17    <li></li>                                       # required, 1->n
18</ul>
19<h4>Dependencies</h4>                               # required
20<table>
21    <tr>                                            # required
22        <th>Name</th>
23        <th>Binaries</th>
24        <th>Version</th>
25    </tr>
26    <tr>                                            # required
27        <td></td>                                   # requited
28        <td>
29            <ul>
30                <li></li>                           # 0->n
31            </ul>
32        </td>
33        <td></td>                                   # required
34    </tr>
35</table>
36</table>
37<h4>Configuration files</h4>
38<p></p>
39<h4>Systemd unit files</h4>
40<p></p>
41<h4>Licenses</h4>                                   # required
42<ul>                                                # required
43    <li></li>                                       # required, 1->n
44</ul>
45<h4>YAML data</h4>                                  # required
46<pre>                                               # required
47    <--YAML-->                                      # required
48    ${script_name}:                                 # required
49        category: ${category_name}                  # required
50        running user: ${running_user}               # required
51        configuration files:
52            paths:
53                - ${path_i}                         # i = 0->n
54        systemd unit files:
55            paths:
56                service:
57                    - ${path_i}                     # i = 0->n
58                timer:
59                    - ${path_i}                     # i = 0->n
60    <!--YAML-->
61</pre>
62<hr />                                              # required

Coding standards

Python

  • scripts must be written in Python >= 3.5 and Python < 4.

  • scripts must start with #!/usr/bin/env python3

  • access to the shell is done via the fpyutils module when possible

  • code must be validated through $ make pep

  • YAML must be used for configuration files:

    • 4 space indentation

    • when present, the notify section must be like this:

    notify:
    email:
        enabled: true
        smtp server: 'smtp.gmail.com'
        port: 465
        sender: 'myusername@gmail.com'
        user: 'myusername'
        password: 'my awesome password'
        receiver: 'myusername@gmail.com'
        subject: 'some subject'
    gotify:
        enabled: true
        url: '<gotify url>'
        token: '<app token>'
        title: 'some title'
        message: 'some message'
        priority: 5

Shell

  • scripts must be GNU Bash compatible

  • scripts must start with #!/usr/bin/env bash

  • scripts must set these options: set -euo pipefail

  • all variables must be enclosed in braces

  • all variables must be quoted, except integers