S’inscrire sur la forge git.spip.net
Pour proposer une modification sur git.spip.net il faut :
- lire la charte d’accueil de SPIP, puis, si vous souscrivez à celle-ci ;
- s’inscrire sur le forum de discussion ;
- demander un accès à la forge sur sa page d’inscription.
Règles de contribution
- Créer un ticket sur https://git.spip.net/spip/spip/issues avant d’envoyer une proposition (qu’on nomme PR [1]).
- Créer une copie personnelle du dépôt (un fork) et y créer une branche qui contiendra les modifications proposées. Celle-ci doit-être nommée issue_xxx où xxx est le numéro du ticket associé.
- Les messages des commits de la branche issue_xxx doivent suivre la nomenclature des Commits Conventionnels. Le corps du message doit être clair et explicatif : décrire le problème traité et les évolutions ou corrections apportées. De plus, la série de commits doit être linéaire (sans commits de merge).
- Une fois la branche finalisée, faire une demande de fusion via l’interface de la forge en cliquant sur « nouvelle demande de fusion » depuis la branche en question. S’assurer que la PR ne contient pas de conflits. S’il y en a corriger à l’aide de
git rebaseetgit force push. La demande sera passée en revue et testée par les membres de l’équipe. Elle ne pourra être fusionnée qu’après avoir reçu au moins deux approbations de ces membres. - La branche issue_xxx peut être supprimée après fusion.
Une fois il la branche fusionnée, l’équipe de maintenance se chargera d’ajouter une ligne dans le fichier CHANGELOG,
Les mêmes règles s’appliquent aux membres de l’équipe, pour qui il est recommandé de toujours passer une PR avant d’intégrer du code dans la branche master. Toutefois, si le patch est vraiment mineur et que la personne est certaine que cela ne casse rien, elle peut décider de l’envoyer directement dans la branche master à condition d’en assurer le suivi. Ces membres peuvent créer la branche directement dans le dépôt, sans fork.
À propos des Commits Conventionnels et des fichiers CHANGELOG
Lire les articles :
- Écrire un message de commit
- Tenir un CHANGELOG
À propos de la fusion de branche
Dans la communauté SPIP (core et plugins) nous n’utilisons pas les commits de fusion de branche. Nous préferons, pour avoir un historique plus linéaire, utiliser un rebasage puis une avance rapide.
# Au sein de la branche à fusionner
$ git rebase master
# Bascule vers la branche principal
$ git switch master
$ git merge branche_a_fusionner
Dans l’interface de Gitea, choisir "Rebaser puis avancer rapidement".
Il en est de même pour les pulls.
On optera donc pour la config git globale suivante :
$ git config --global pull.ff only
$ git config --global pull.rebase = true
$ git config --global merge.ff = true
Règle de cherry-pick
En général, lors d’un git cherry-pick, utiliser l’option -x.
Règles de présentation et d’écriture
Consulter les règles de codage.
Règles de programmation
Réfléchir
Avant de programmer une nouvelle fonctionnalité, réfléchir...
- méthodes et algorithmes utilisés pour l’implémentation : légèreté, performance, robustesse (ne pas hésiter à faire quelques calculs grossiers pour valider les choix) ;
- adéquation au projet : portabilité, sécurité, souplesse ;
- implications sur les autres fonctionnalités : modifications et ajouts à faire sur les fonctionnalités existantes ;
- place « naturelle » pour cette fonctionnalité dans le projet : en matière d’interface, de fichiers...
Ne pas négliger la factorisation ou mise en commun du code (par des fonctions, notamment dans des fichiers à inclure). Éviter par contre le plus possible les fichiers inclus contenant du code hors fonctions (sauf lorsque c’est « naturel » et voulu).
Nommer
D’une manière générale, les noms seront ni trop brefs, ni trop longs ; ils seront suffisamment explicites. Cette règle est particulièrement importante pour les variables globales, qui peuvent être partagées entre plusieurs fichiers et de nombreuses fonctions. Pour les variables locales (i.e. à une fonction), la règle est plus souple. Notamment, on peut employer des variables d’une lettre, par exemple pour obtenir des expressions plus compactes. Remarquer que dans tous les langages de programmation, un certain nombre de lettres sont par tradition associées à certains usages (exemples : $i, $j pour des compteurs de boucles, $n pour un dénombrement, $t pour un instant ou une durée en secondes...). Ne pas détourner ces conventions permet lors de la lecture du code d’être plus vite dans le bain.
Tester
Une fois une modification importante apportée, il est bon de la tester soi-même, sans attendre que quelqu’un·e d’autre le fasse à sa place. Dans le cadre de SPIP, cela veut dire vérifier que le programme marche de manière correcte sur un certain nombre d’hébergeurs et de configurations (par exemple : différentes versions de PHP, de MySQL, restriction plus ou moins grande des droits d’accès aux répertoires...) ; mais aussi qu’un certain nombre de situations parmi les plus courantes (dans le cas d’une interface graphique notamment) sont traitées correctement.