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 |
---|---|---|
|
|
|
Scripts page
Variables
Variable name |
Description |
---|---|
|
the name of the script |
|
the name of the category that identifies the directory where the source file have been placed |
|
see the |
|
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 possiblecode 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