Publier un plugin
Cette page est générée depuis docs/plugins/PUBLISHING.md · Modifier cette page sur GitLab
Nommer
- Le
namedu manifeste est en kebab-case (a-z,0-9, tirets), unique, et c'est le nom du dossier :<dataDir>/plugins/<name>/. - Le dépôt et le paquet s'appellent
mergerie-plugin-<name>(mergerie-plugin-sonar,mergerie-plugin-argocd). Le générateur le fait. - Les tables sont
plugin_<name>_*, les routes sous/api/plugins/<name>/, les clés de traduction préfixées<name>., les événements émis préfixés<name>., les variables d'environnement<NAME>_*. Ce n'est pas une convention : le chargeur le fait respecter.
Le README attendu
Un lecteur doit y trouver, dans cet ordre : ce que fait le plugin (trois lignes) ; les permissions demandées et pourquoi, en nommant ce qui est appelé sur le réseau et ce qui est lancé sur la machine ; les réglages (et lesquels sont des secrets) ; comment l'installer (dossier, adresse git) ; comment le tester (npm test) ; la licence ; comment signaler un problème.
Licence : AGPL, et ce que ça implique
Mergerie est sous AGPL-3.0-only. Un plugin s'exécute dans le même processus (embarqué) ou dans un worker du même programme (tiers) en appelant son API : il forme avec Mergerie une œuvre combinée. En clair :
- un plugin que vous distribuez (publié, vendu, remis à un client) doit être sous une licence compatible avec l'AGPL-3.0 — l'AGPL-3.0 elle-même, la GPL-3.0, ou une licence permissive (MIT, BSD, Apache-2.0) qui permet la combinaison. Le générateur met
AGPL-3.0-only; - un plugin que vous gardez pour vous ou votre entreprise, sans le distribuer, n'est soumis à aucune obligation de publication ;
- si vous rendez Mergerie accessible à des utilisateurs par le réseau (un serveur partagé), l'AGPL demande que ces utilisateurs puissent obtenir les sources de ce qu'ils utilisent — Mergerie ET les plugins qui tournent dedans.
Ce n'est pas un avis juridique ; en cas de doute, demandez-en un. Ce qui compte pour nous : qu'un plugin publié soit lisible — ses utilisateurs lui confient leurs jetons et leur machine.
Être listé dans COMMUNITY.md
Ouvrez une merge request sur le dépôt de Mergerie qui ajoute une ligne à COMMUNITY.md : nom, une phrase, l'adresse du dépôt, la licence, l'apiVersion ciblée, les permissions demandées. Conditions : un README conforme, une CI qui lance les tests du plugin, une licence compatible, et un plugin.json que validateManifest accepte. La liste n'est pas un registre : rien n'est téléchargé automatiquement, et Mergerie ne vérifie pas le code des plugins qui y figurent.
Versionner
version suit semver. Une mise à jour se fait par Rescanner (la nouvelle version est signalée) puis désactiver/réactiver ; vos migrations de tables doivent donc être additives et rejouables en avant. Changez l'apiVersion ciblée quand Mergerie en publie une nouvelle (MIGRATION.md).