Overview

Artifact ID: 3f3c095c5e8f1cab111be0887d4665bb1b0c8039
Page Name:Documentation développeur
Date: 2019-05-26 14:05:18
Original User: bohwaz
Mimetype:text/x-markdown
Parent: 8f4815c54ca4c52fdea83d17ff043267af64d248
Content

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 : 5.6 et plus (passage à PHP 7.0 requis au minimum, prévu courant 2019-2020)
  • Base de donnée utilisée : SQLite 3
  • Les principes derrière le design de Garradin

Contacter les développeurs-euses

  • Il existe deux listes de discussion : aide pour l'entraide entre utisateurs-trices, et patch@garradin.eu pour soumettre des contributions à Garradin ** Pour s'abonner à la liste patch, envoyer un email à patch-join@garradin.eu
  • Sur IRC : salon #garradin sur irc.freenode.net
  • Sur Jabber : salon garradin sur chat.jabberfr.org

Contribuer au code de Garradin

  • 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 (certaines règles ne sont pas des plus pratiques).
  • Guide de style du code

Autres pages de la documentation développeur

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 Garradin.

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/garradin/ garradin.fossil
    • Créer un nouveau répertoire où l'on veut récupérer le code et s'y placer : par exemple ~/fossil/garradin/
    • Lancer : fossil open ~/fossil/garradin.fossil dev
    • Se placer dans le répertoire contenant le source de Garradin : cd src
    • Installer les dépendances : make deps

Pour tester Garradin 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 ?

  • 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 patchs : patch@garradin.eu (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.

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

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

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 : github.com/kd2org/garradin

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.