Contribuer au développement de SPIP

S’inscrire sur 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 en écriture en utilisant le formulaire dédié sur contrib.spip.net.

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_xxxxxx 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. De plus, il faut bien veiller à ajouter une ligne dans la fichier CHANGELOG du dépôt dans un commit à part afin d’éviter les conflits lors de la fusion. Pour finir, la série de commits doit être linéaire (sans commits de merge).
  4. Une fois la branche finalisée, faire une demande de fusion via l’interface de Gitea 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.
  5. La branche issue_xx 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

La liste des types disponibles pour les commits conventionnels est la suivante : build, change, chore, ci, deprecate, doc, feat, fix, perf, remove, revert, security, style, test, i18n (détails sur git.spip.net). Le type peut éventuellement être complété par un scope entre parenthèses afin de préciser le composant ou la fonctionnalité modifiée (exemples avec les commits 13a90d3878 et 5512ce374b).

Le pied de page du message doit contenir une référence au ticket lié à la PR sous la forme de Refs: #XXX ou Fix: #XXX pour fermer le ticket automatiquement lors de la fusion.

Exemple de log de commit complet :

fix: réparer le lien vers la licence GPL dans le pied des pages du privé

en le remplaçant par un simple lien vers le site officiel gnu.org

Fix: #5328

Les fichiers de CHANGELOG suivent la norme Tenez un Changelog. Chaque entrée du changelog doit :

  • référencer le ticket (ou la PR s’il n’y a pas de ticket correspondant)
  • décrire clairement et de manière concise les modifications apportées par la PR (pour cela, vous pouvez simplement reprendre la première ligne du message de commit)

Exemple d’entrée de changelog correspondante au log de commit précédent :

- #5328 Réparer le lien vers la licence GPL dans le pied des pages du privé

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 (par exemple : Altern, Free...) 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.

Notes

[1PR est l’acronyme de « Pull Request », c’est à dire une proposition de modification.

Portfolio

Auteur L’équipe de SPIP Publié le : Mis à jour : 04/10/22

Traductions : عربي, català, corsu, English, Español, français, italiano