# Contribuer à Enclume

Deux formes de contribution, très différentes par leur difficulté.

## Proposer un pack — le plus utile

Un pack décrit une technologie : un modèle d'hôte et ses sondes. C'est ce qui fait la valeur
d'Enclume, et c'est accessible à quiconque supervise cette technologie au quotidien.

**Depuis le site**, bouton « Proposer un pack » : collez votre YAML, il est vérifié
immédiatement, et une demande de fusion est ouverte après relecture.

**Par pull request**, si vous préférez : un fichier dans `catalog/<catégorie>/<id>.yml`.

### Le format

```yaml
id: app-rabbitmq              # minuscules, chiffres et tirets
name: RabbitMQ                # nom lisible, affiché dans le catalogue
category: applications        # une des catégories ci-dessous
status: to-verify             # verified seulement si éprouvé sur un central réel
plugin: centreon_rabbitmq_restapi.pl
description: Supervision d'un broker RabbitMQ via son API de management.

host_template:
  name: App-RabbitMQ-custom   # <Famille>-<Techno>-custom
  alias: Applicatif RabbitMQ
  parents: [generic-active-host-custom]
  macros:
    - {name: RABBITPORT, value: "15672", description: "Port de l'API"}
    - {name: RABBITPASSWORD, value: "", description: "Mot de passe", is_password: true}

prerequis:                    # facultatif mais précieux
  paquets:
    debian: [libwww-perl]
    rhel: [perl-libwww-perl]
  notes: |
    Activer le plugin de management et créer un compte en lecture seule.

groupe_hote:                  # le groupe dans lequel ranger les hôtes
  name: HG-App-RabbitMQ
  alias: RabbitMQ

notification:                 # la chaîne d'alerte livrée avec le pack
  perimetre: RabbitMQ
  calendrier:                 # le pack apporte le sien, il ne réutilise pas celui du central
    name: TP-App-RabbitMQ-24x7
    modele: 24x7              # 24x7 ou Heures-Ouvrees : le rythme copié
    alias: RabbitMQ, en permanence
  groupe: CG-App-RabbitMQ     # CG-<Famille>-<Techno>
  criticite: Majeure
  impact: "Échanges entre applications interrompus"
  options_hote: d,u,r
  options_service: w,c,r
  intervalle: 30

services:
  - name: Queues              # donnera le modèle App-RabbitMQ-Queues
    alias: Queues
    description: Messages en attente dans les files
    default: true             # false pour une sonde décochée par défaut
    line: "$CENTREONPLUGINS$/centreon_rabbitmq_restapi.pl --plugin=… --mode=queues …"
    macros:
      - {name: WARNING, value: "1000", description: "Seuil warning"}
```

### Les catégories

Ce sont celles des connecteurs de supervision Centreon, pour qu'un pack se range là où on
ira le chercher dans la documentation officielle :

`operating-system`, `network`, `hardware-server`, `storage`, `database`, `applications`,
`virtualization`, `protocol`, `ups-pdu`, `printer`, `sensor`, `cloud`, `toip-voip`,
`blockchain`, `centreon`.

Le fichier se dépose dans `catalog/<catégorie>/<id>.yml`, et le champ `category` porte la
même valeur.

### Les règles

- **Pas de point-virgule** dans une ligne de commande : c'est le séparateur CLAPI, il casserait
  le fichier d'import.
- **Les seuils en macros** `$_SERVICEXXX$`, jamais en dur. C'est tout l'intérêt d'un modèle.
- **Ce qui est commun à l'hôte va sur l'hôte** : ports, comptes, options du plugin. Ce qui est
  propre à une sonde va sur la sonde : seuils, filtres.
- **Aucun mot de passe réel.** Valeur vide et `is_password: true`.
- **Un groupe d'hôtes.** Nommé `HG-<Famille>-<Techno>`. Un hôte sans groupe devient
  introuvable dès que le parc grandit, et les droits comme les filtres s'appuient dessus.
- **Une chaîne de notification.** Un pack qui supervise sans prévenir personne n'a pas
  d'intérêt : `calendrier`, `groupe` et `impact` sont attendus. Choisissez `24x7` pour ce
  dont la panne réveille quelqu'un, `Heures-Ouvrees` sinon. Les calendriers livrés par
  Centreon. Chaque pack apporte **son propre** calendrier, nommé `TP-<Famille>-<Techno>-<rythme>` :
  ajuster les plages d'une technologie ne doit pas modifier celles de tout le central.
- **`status: verified`** uniquement si vous avez exécuté ces commandes sur un Centreon. Sinon
  `to-verify`, c'est honnête et c'est utile.
- `$CENTREONPLUGINS$` est remplacé par le répertoire de plugins choisi par l'utilisateur.

### Le plus précieux

Vérifier un pack existant marqué `to-verify` vaut autant qu'en écrire un nouveau. Un
`--list-mode` sur le plugin concerné, une exécution réelle, et le passage en `verified` :
c'est ce qui rend le catalogue fiable.

## Contribuer au code

```bash
python3 -m venv .venv && . .venv/bin/activate
pip install -r requirements.txt pytest ruff
python -m pytest -q
sh tests/interface.sh
```

Avant toute proposition, la revue décrite dans [docs/CONVENTIONS.md](docs/CONVENTIONS.md) :
`ruff check`, la suite de tests, le test d'interface. Les conventions de nommage y sont aussi.

Une règle traverse tout le projet : **le serveur n'exécute jamais rien**. Ni CLAPI, ni
prérequis, ni contribution. Il écrit des fichiers que l'utilisateur relit avant de les jouer.
Toute proposition qui s'en écarte sera refusée, quel que soit son intérêt.

## Signaler un problème

Un pack dont le CLAPI généré ne passe pas sur votre central est un signalement de première
importance : indiquez la version de Centreon, le pack, et le message d'erreur de `centreon`.