Contribuer au développement de SPIP

S’inscrire sur la forge git.spip.net

Pour proposer une modification sur git.spip.net il faut :

1. lire la charte d’accueil de SPIP, puis, si vous souscrivez à celle-ci ;
2. s’inscrire sur le forum de discussion ;
3. demander un accès à la forge sur sa page d’inscription.

Règles de contribution

1. Créer un ticket sur https://git.spip.net/spip/spip/issues avant d’envoyer une proposition (qu’on nomme PR [1]).
2. 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é.
3. 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.
4. De plus, il faut bien veiller à ajouter une ligne dans le fichier CHANGELOG du dépôt dans un commit distinct sur la même branche afin d’éviter les conflits lors de la fusion. Pour finir, la série de commits doit être linéaire (sans commits de merge).
5. 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 rebase et git 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.
6. La branche issue_xxx peut être supprimée après fusion.

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 à vos lecteurs 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 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.