Documentation développeur⋅euse

Design

• Les principes derrière le design de Paheko
• Réflexions sur la conception de la compta
• Vue d'ensemble de Paheko, tour d'horizon de l'architecture et des processus clefs du logiciel

Documentation approfondie

• Les entités de base de données
• Développer avec Smartyer, le moteur de template de Paheko (partie "admin")
• Documentation de Brindille, le langage des templates utilisateur et des modules
• Le format de stockage du contenu des pages web
• Squelettes
• Développer un plugin
• Les signaux des plugins

Informations sur le projet

• Licence utilisée : Affero GPL v3 (basiquement identique à la GPL mais rajoute une obligation de distribuer le code pour une utilisation sur un serveur même si pas de distribution de binaire)
• Langage utilisé : PHP
• Versions supportées : 7.4 et supérieur
• Base de donnée utilisée : SQLite 3 (3.16 et supérieur)

Contacter les développeurs-euses

• Il existe deux listes de discussion : aide pour l'entraide entre utisateurs-trices, et dev pour soumettre des contributions à Paheko
• Sur IRC, discussions entre développeureuses : salon #garradin sur irc.libera.chat
• Aussi disponible via ce webchat

Contribuer au code de Paheko

• On utilise Fossil qui sert de DVCS, wiki, gestionnaire de tickets, etc.
• On utilise SQLite3 comme base de données qui stocke tout : compta, membres, configuration, fichiers, wiki... Ainsi un seul fichier à sauvegarder et à gérer.
• On suit PSR-4 pour le nommage des classes et namespaces etc.
• Convention de code : principalement PSR-1 et PSR-2, enfin pas à la lettre mais globalement. Voir la Convention de code complète.

Généralement nous n'acceptons que les patch et pull requests qui corrigent un bug ou une faille, ou des petits détails mais pas de grosse nouvelle fonctionnalité à moins que ça ait été discuté auparavant.

FAQ

Comment installer une copie de la version de développement pour tester ?

• Télécharger le ZIP du trunk
• Dé-zipper le fichier
• Exécuter la commande make deps (depuis la racine src/) pour télécharger les dépendances
• Suivre les instructions classiques : Installation

Alternative si vous n'avez pas make installé : télécharger le ZIP de la librairie KD2, le dé-zipper, et déplacer le répertoire lib/KD2 de la librairie dans le répertoire src/include/lib/KD2 de Paheko.

Obtenir une copie du repository de développement

• Installer Fossil, l'outil de versionnement utilisé pour le développement (sur Debian et Ubuntu : apt-get install fossil)
• Se placer dans un répertoire où l'on souhaite copier le fichier contenant le repository (il contiendra l'intégralité du code, mais aussi toutes les modifications réalisées, les tickets, le wiki, etc.) : par exemple ~/fossil/
• Lancer : fossil clone https://fossil.kd2.org/paheko/ paheko.fossil
  • Activer les liens symboliques : fossil -R paheko.fossil settings allow-symlinks on
  • Créer un nouveau répertoire où l'on veut récupérer le code et s'y placer : par exemple ~/fossil/paheko/
  • Lancer : fossil open ~/fossil/paheko.fossil dev
  • Se placer dans le répertoire contenant le source de Paheko : cd src
  • Installer les dépendances : make deps

Pour tester Paheko avec le serveur web intégré à PHP lancer : make dev-server

Et se rendre à l'adresse http://localhost:8082/ avec son navigateur web.

Comment proposer un patch avec Fossil ?

Déjà, si vous avez l'habitude d'utiliser Git, vous pouvez proposer une PR sur le miroir Github: https://github.com/kd2org/paheko

• Créer sa propre branche de développement : fossil branch new --private perso trunk
• Se positionner sur cette branche : fossil checkout perso
• Faire ses modifs sur le code...
• Exporter un patch : fossil diff -N --branch perso > mon-patch.txt
• Envoyer le patch à la liste de discussion des dévs : dev(arobase)paheko.cloud (en pièce jointe, et ne pas oublier d'inclure une description de ce que le patch fait :)

Pourquoi SQLite seulement ? Pourquoi pas MySQL, PostgreSQL, etc. ?

Parce que c'est une manière simple d'avoir toutes les données de l'application regroupées au même endroit, et que l'application puisse gérer ses propres imports / exports et sauvegardes. De même cela simplifie grandement l'installation pour les débutants : rien à configurer de technique.

SQLite est une base de données très puissante et rapide qui offre de nombreuses possibilités avancées. L'avantage principal est que la base de données est comprise en un seul fichier, simplifiant sa gestion et réplication. Enfin, sa résilience et ses performances ne sont plus à prouver, d'autant plus maintenant qu'elle est la base de données la plus utilisée au monde. En se concentrant sur une seule base de données il est possible d'obtenir des améliorations et simplifications qu'il ne serait pas possible d'avoir en devant rester générique pour fonctionner avec plusieurs bases de données.

De fait il n'est pas prévu de permettre d'utiliser une autre base de données, les avantages à une telle possibilité sont bien moindres comparés à tous les inconvénients.

SQLite a des risques de pertes de données ?

Non, à moins de l'utiliser sur du NFS. Voir comment corrompre une base de données SQLite.

SQLite est la base de données la plus utilisée au monde, elle est dans tous les téléphones, tous les ordinateurs, mais aussi dans des voitures, des avions, des satellites, etc. Voir utilisations célèbres de SQLite et utilisations les plus courantes de SQLite.

C'est aussi la base de données la plus testée au monde.

Pour info, MariaDB/MySQL et PostgreSQL stockent aussi leurs données dans des fichiers, et si l'un deux est corrompu, les données seront également perdues, c'est commun à toutes les bases de donnée ;)

Les performances de SQLite ne sont pas plus mauvaises que celles de MySQL ou PostgreSQL ?

Cela dépend de l'utilisation. Pour Paheko, SQLite convient parfaitement et à ce jour nous n'avons pas eu de problème avec les 5000+ associations gérant 150.000+ membres :)

Généralement SQLite est beaucoup plus rapide que les autres bases de données, car il n'y a pas de connexion réseau à faire : dans une base de données de type MySQL chaque requête coûte quelques millisecondes car il faut contacter le serveur de base de données et attendre sa réponse. Avec SQLite la base de données est sur la même machine : pas de réseau, et chaque requête ne coûte quasiment rien (sans prendre en compte la complexité de la requête).

D'autres personnes ont mené des tests et par défaut SQLite peut offrir des performances très correctes sur un VPS bas de gamme : jusqu'à 400 écritures par seconde. Pour Paheko 95% des requêtes sont en lecture, et dans la majorité des cas il n'y a jamais plus de 2 ou 3 requêtes par seconde. En réalité cela veut dire qu'une association ne rencontrerait des problèmes qu'avec plusieurs centaines de milliers, ou millions d'utilisateurs.

Pourquoi Fossil et pas Git ?

Fossil est un gestionnaire de projet décentralisé complet. Ce n'est pas juste un DVCS comme Git mais un véritable gestionnaire de projet incluant un wiki, une gestion de tickets, une interface web, une gestion d'utilisateurs, etc etc. Git, SVN, Mercurial et autres ne sont que des DVCS : ils ne permettent de versionner que le code.

De plus Fossil est bâti sur SQLite et est l'œuvre de l'auteur de SQLite, cela fait de lui le gestionnaire de version le plus robuste qui soit, et le stockage de ses données est simplissime !

Et si je préfère Git ?

Pas de souci, nous avons aussi un miroir Git : https://github.com/kd2org/paheko

Vous pouvez le cloner et y proposer des Pull Request si vous voulez :)

Il faut juste savoir que le développement principal se fait sur Fossil, et c'est là que sont les tickets, la doc, etc.