FAQ pratique : Comment SPIPer avec git.spip.net

Pour contribuer à cette FAQ : n’hésitez pas à répondre aux questions sans réponse. Vos textes ne doivent pas être généraux mais concerner spécifiquement git.spip.net.

Utiliser et exploiter la forge logiciel

1. Faut-il s’inscrire pour récupérer le code d’une contribution ?

Non : on peut cloner un dépôt (en anglais repository, abrégé repo), ou plus simplement juste télécharger son code, sans devoir s’inscrire sur git.spip.net.

• Pour télécharger, on utilisera le bouton “Code” sur la page d’un dépôt, afin de pouvoir télécharger un dossier compressé au format désiré (zip, tar.gz, tar.bz2 ou tar).

  

  Le téléchargement permet de récupérer le zip de la contribution et de l’installer pour SPIP. Cependant ce n’est pas un dépôt git qu’on récupère ainsi, et on ne pourra pas utiliser git dessus, par exemple pour le mettre à jour ou pour commiter. Si on veut pouvoir mettre à jour le source du plugin au moyen de git (git pull) et commiter (git commit puis git push), il faut cloner le dépôt.

• Pour cloner, la commande est

  git clone url_repo

  Où url_repo est l’adresse HTTPS ou SSH du dépôt (voir ci-dessous).

2. Que sont les adresses SSH et HTTPS d’une contribution ?

Un dépôt peut être accédé par les deux protocoles SSH et HTTPS, et propose donc des URLs pour chacun de ces protocoles. Ces deux URLs sont indiquées sur les pages du dépôt.

Par exemple, pour cloner facteur, on utilisera l’une des 2 lignes :

• URL HTTPS :

  git clone https://git.spip.net/spip-contrib-extensions/facteur.git

• URL SSH :

  git clone git@git.spip.net:spip-contrib-extensions/facteur.git

Tout le monde peut utiliser l’URL HTTPS, mais il faut être inscrit et avoir associé une clé SSH à son compte et en local pour utiliser l’URL SSH. Cela permet également de commiter.

Contribuer aux dépôts logiciels

3. Faut il s’inscrire pour pouvoir commiter ?

Oui, il faut s’inscrire sur git.spip.net et accepter la charte de la zone pour pouvoir commiter. Consultez aussi la charte d’accueil de SPIP.

S’inscrire permet ensuite de commiter sur un dépôt git.

• Pour un dépôt cloné par HTTPS : on peut commiter sans clé SSH en indiquant simplement son login et son mot de passe git.spip.net lors du push :

  git push origin branche

  -> Invite de login (pseudo ou mail fonctionnent) -> Invitede mot de passe.

• avec l’URL SSH, il faut avoir créé une clé SSH (pour cela, suivre les indications de Add an SSH key to your GitLab account), et l’avoir déclarée à git.spip.net : on transfère le contenu de la clé publique dans la configuration du compte : Préférence > Accès > Clés SSH. Votre authentification sera ensuite automatique et transparente : plus besoin de mot de passe.

4. Raccourcis sur git

Ces raccourcis permettent de pointer directement un des éléments dans un ticket ou un commentaire publié sur git.spip.net.

Raccourci	Description
#123	ticket ou PR 123, dans le projet courant
orga/projet@sha	raccourci vers le commit sha dans le projet de l’orga
orga/projet#issue	raccourci vers le ticket “issue” dans le projet de l’orga
orga/projet!pr	raccourci vers la PR

5. Quand déclarer un changement de version dans paquet.xml ?

Les numéros de versions sont déclarés dans paquet.xml ainsi que l’état du plugin : stable, dev, test. Dans tous les cas, le numéro de version respecte l’esprit du versionnage sémantique.

• les PR concernant un plugin de la dist ne doivent PAS modifier un changement de version. C’est l’équipe noyau de SPIP qui gère ces modifications.
• Pour les autres plugins… c’est bien comme vous voulez, en accord avec le ou les auteurs du plugin, mais de préférence pas dans une PR s’il y a des risques de conflits avec d’autres PR. (voir #Dans-une-PR-faut-il-actualiser-le-...)

6. Comment demander à SVP de mettre à jour le zip proposé ?

Comment informer SVP qu’il y a une mise à jour et que le zip qu’il propose doit être mis à jour afin que tous les utilisateurs de SPIP puissent bénéficier de la nouvelle version du plugin ?

Il faut créer un nouveau tag git et le “débardeur” se charge ensuite de mettre à jour le zip, qui sera proposé dans la partie privée de votre SPIP.

Il est possible de le faire à partir de l’interface de git.spip.net en sélectionnant + > Nouvelle étiquette (ou via l’interface des étiquettes, accessible en cliquant sur le nombre).

En ligne de commande

Exemple : pour distribuer la version 1.0.0, cette version doit être indiquée dans le paquet.xml, et le tag 1.0.0 (anciennement v1.0.0) doit être créé. Pour créer le tag, mettez-vous dans le dossier source racine du plugin, et faites :

git tag -d v1.0.0
git push origin :refs/tags/v1.0.0

7. Faut-il économiser les tags ?

Sous git, créer un tag n’a qu’un coût assez faible. Il faut donc créer un tag chaque fois que c’est utile, c’est-à-dire chaque fois qu’on veut mettre à disposition des utilisateurices une nouvelle version du plugin.

En même temps ça se traduit par un ZIP, faut pas en abuser sans utilité.

8. Peut-on effacer ou réutiliser un tag ?

Un tag sert à la fois pour demander à distribuer une version, ET à référencer une étape de développement et d’évolution du code. Supprimer un tag perd donc cette référence.

Il ne faut jamais recycler un tag : Si d’aventure il vous arrivait de créer un tag puis de changer d’avis, il est possible de le supprimer, mais dans ce cas il ne faut surtout pas le réutiliser plus tard. SVP ne s’y retrouve pas : il faut monter la version dans paquet.xml, et faire un nouveau tag.

9. Comment importer sur git.spip.net un plugin développé sur GitHub ou GitLab ?

Il y a deux manières de faire : en cliquant sur un bouton (simple et automatique) ou en ligne de commande (personnalisable au besoin).

• Automatiquement : sur git.spip.net, chacun peut trouver, à coté de son avatar, une opération appelée “Nouvelle migration”. Elle permet en un seul formulaire de transférer un dépôt github ou autre vers son organisation personnelle sur la forge ou dans une des organisation spip-contrib.

• En ligne de commande : Chaque repo git, qu’il soit distant ou local, possède un historique, et qu’on peut synchroniser les historiques entre les repos
  Pour importer un repo github ou gitlab sur git.spip.net,

1. Tu clones en local ton repo
2. Tu crée un nouveau repo sur git.spip.net
3. Tu références ce repo distant dans ton repos local avec git remote add <unnomdetonchoix> <lurldureposdistant>. <unnomdetonchoix> est le nom qui permet de référencer (depuis ton repos local) le repos distant nouvellement créé. Mais si en fait tu souhaites ne garder qu’un seul dépôt distant comme dépôt de référence, plutôt qu’ajouter la nouvelle url à l’url existante, tu peux aussi simplement la remplacer : git remote set-url origin <lurl du repos distant>.
4. Tu fais git push <unnomdetonchoix>

Rq : Par convention, lorsqu’on clone une depot distant, il est référencé avec le nom origin comme dépot local. Mais tu peux en référencer plusieurs.
Une pratique courante est
-  upstream pour désigner le repos communautaire officiel du projet
-  origin pour designer le repos distant “personnel”

10. Est-ce une bonne pratique de récupérer le code de tous les plugins de la zone ?

Pour ne pas surcharger le serveur, il ne faut localement cloner que les plugins dont on a besoin. Donc si vous n’avez pas besoin de tous les plugins, ne clonez pas tous les plugins.

Dans certains cas toutefois, on a parfois besoin des sources de tous les plugins, par exemple pour faire des recherches globalement sur tout le code afin d’étudier les cas d’usage d’une fonction ou pour corriger tous ces appels.

Dans ce cas, utilisez le script mirror : il interroge l’API GitLab pour avoir la liste des repositories de chaque organisation, et récupère ou met à jour le dépôt s’il a été modifié depuis le dernier pull. Un cache de 10 min évite de trop solliciter GitLab. Les repositories en erreur ou vides sont détectés et à la fin on a un bilan final.

11. Comment être notifié des modifications apportées sur un plugin, ou ne pas l’être ?

Toute personne inscrite sur git.spip.net est abonnée à l’ensemble des dépôts, et vous êtes notifiés des divers échanges qui ont lieu sur ces divers dépôts : tickets, PR, ...
En effet, votre compte est configuré par défaut de telle sorte que toutes les notifications vous parviennent. Vous pouvez modifier cette configuration depuis git.spip.net/-/profile/notifications

12. Comment étendre ou restreindre la compatibilité SPIP d’un plugin ?

Autant étendre l’intervalle de compatibilité avec SPIP sur une branche existante ne pose pas de problème particulier (sauf à bien être certain de pas avoir à revenir en arrière), autant réduire l’intervalle de compatibilité en enlevant le support de versions SPIP ne doit pas se faire à la légère.

Pour illustrer, dans le cas précis, si on doit faire un fix de sécurité ou même a minima un bugfix parce qu’un vieux site continue de tourner sur une veille version du plugin, on est totalement coincé.

La bonne pratique, quand on veut abandonner le support de vieilles versions de SPIP est toujours de faire une nouvelle branche.

Ici donc, il aurait faire une branche de maintenance pour la version v1 du plugin, et passer le master en branche v2. Au passage, cela permet également d’être plus ambitieux et de monter la version mini de SPIP à 3.2 par exemple, laissant le support des plus vieux SPIP à la branche de maintenance si besoin et c’est ce que j’ai fait sur le plugin vérifier ce jour.

( source)

13. Proposer une modification, faire une PR

Faire une PR, c’est proposer l’intégration de modifications (https://git.spip.net/spip/dist/pulls). Ces modifications doivent auparavant avoir été faite sur une branche ou sur un fork du repo.

Pour un plugin, souvent on ne fait pas de PR on commit direct dans un clone et on push. Pour la dist, c’est différent car sans les droits suffisants on ne peut pas écrire direct dans le code.

Proposer une modification sur un plugin

Pour proposer une modification sur un plugin, il vaut mieux éviter de forker ; il faut simplement créer une nouvelle branche dans le repo collectif et y commiter les modifications.
Le nom de cette branche doit évoquer le motif de sa création : inclure le n° de ticket ou un mot clé évocateur.
Ensuite on fait une PR de la branche vers le master pour proposer de fusionner les modifications apportées.

Proposer une modification sur le core ou un plugin-dist :

À moins de droits spéciaux, on ne peut pas créer une branche sur le repo du core ou d’un plugin-dist (ça dépend des organisations et de vos droits persos sur git.spip.net).
Il faut donc créer un fork perso sur git.spip.net.
Vous pourrez ensuite développer sur une branche spéciale du fork, et faire la PR.

Spiper sur les dépôts protégés

14. Détail des étapes pour faire une PR sur un repo protégé

La dist, c’est plusieurs repos, il faut déjà repérer lequel on veut modifier
et ensuite :
-  forker ce repo avec le bouton “Bifurcation” en haut à droite de sa page git.spip.net
-  modifier le code de ce fork

-  soit sur git direct via l’éditeur en ligne si c’est une toute petite modif,
-  soit après avoir cloné le fork en local, créé une branche spécifique au ticket concerné, fais tes modifs sur cette branche sur le fork en local, puis pushé à nouveau sur le fork

-  puis faire une PR sur git avec le bouton “Nouvelle demande de fusion”, de la nouvelle branche du fork vers le master du repo dist.

15. Git merge ou rebase ?

La réponse à cette question dépend des personnes qui gèrent les projets, et donc des projets.

Voir un exposé général sur les opérations de merge et de rebase, et sur les enjeux du choix entre l’un ou l’autre :
-  https://www.atlassian.com/fr/git/tutorials/merging-vs-rebasing
-  https://delicious-insights.com/fr/articles/bien-utiliser-git-merge-et-rebase/

Certaines personnes tiennent au rebase : « le rebase c’est mieux car on conserve l’historique linéaire et on évite les conflits, et ça évite un commit supplémentaire rien que pour le merge »

D’autres veulent conserver visibles les étapes de développement tickets par tickets, et donc préfèrent merger.

Dans SPIP, la recommandation de l’équipe du core, c’est de fonctionner plutôt par rebase... mais l’outil employé, gitlab, propose le merge par défaut.

Dans tous les cas, il vaut mieux ne pas merger sur un pull, et donc régler ainsi son git local

Pour cela :

git config --global pull.ff only
git config --global pull.rebase true
git config --global merge.ff = true

Voir aussi : www.spip.net - À propos de la fusion de branche

16. Nettoyer après un merge

Le merge ajoute un commit dans l’historique, juste pour indiquer qu’il y a eu merge. On peut le virer, par exemple en le fusionnant avec le commit précédent, avec la commande :
git rebase -i

Voir aussi : git-scm.com - Utilitaires Git - Réécrire l’historique

17. Pour éviter les merge

git fetch : git va chercher les commits qui sont sur le serveur et les récupère en local, dans son arbre, MAIS il ne les checkout pas. En gros tu restes sur le même commit en local, mais simplement git sait maintenant qu’il y a des commits en plus sur le serveur si c’est le cas

git pull : c’est un git fetch + le checkout dans ton répertoire des commits qui arrivent depuis le serveur.

Et c’est là que le problème se pose : si tu as travaillé entre-temps, ton dossier local contient des commits qui ne sont pas sur le serveur, et le serveur contient des commits qui ne sont pas sur ton disque.

Pour ça 2 solutions :

• soit git fait un merge (c’est le réglage par défaut que tu as actuellement), et ça génère sans arrêt plein de commits de merge un peu ennuyeux
  -  * soit git fait un rebase : il va enlever tes commits locaux, remettre les commits qui arrivent depuis le serveur, et rejouer tes commits par-dessus. 99% du temps ça se passe bien, mais parfois il peut y avoir un conflit sur une modification faite des deux côtés. Dans ce cas suivre les indications de git : editer le fichier, résoudre le conflit manuellement, faire un git add dessus, puis un git rebase --continue

Une commande permet que les “pull” se fassent toujours en “rebase” et évite de faire des “merge” sans arrêt sur le master quand quelqu’un a commit en parallèle :

git config --global pull.rebase true

18. Pour proposer une PR, vaut il mieux forker un repo ou bien juste créer une branche sur le même repo ?

La logique du fork est celle de github, où chacun⋅e code dans son coin puis fait valider une PR par un responsable principal de projet. C’est ce qu’il faut faire pour le core (organisation : https://git.spip.net/spip)

Sur la logique plus communautaire des plugins de spip-zone, il est possible de juste faire une branche sur le dépot commun, sans avoir forké, puis de faire une PR sur ce même dépot.

Autrement dit :
-  pour le core: forker le repo sur git.spip, cloner le fork localement, créer une branche
-  pour un plugin communautaire : cloner directement le repo localement, créer une branche. Puis commiter localement, pusher puis faire la PR sur git.spip. Rq : Il est éventuellement possible de commit direct dans le master si vous êtes absolument certain de ce que vous faites et que ça ne nécessite pas une validation.

19. Dans une PR, faut-il actualiser le numéro de version ?

Quand on propose une PR, on sait pas si elle sera validée et fusionnée ou bien discutée pour être améliorée ou rejetée. Donc, on ignore à l’avance le temps que ça prendra et dans quel ordre les PRs seront mergées. Si les numéros de versions étaient actualisés dans les PR, ça pourrait provoquer des conflits selon l’ordre de merge. Les PRs ne doivent donc PAS modifier les numéros de version dans paquet.xml. Ce doit être fait à part, sans PR.

20. Comment recréer un dépôt existant sur une autre infrastructure ?

Si l’import d’un dépôt via l’outil de gestion des dépôts ne fonctionne pas, il est possible de créer un nouveau dépôt sur l’infrastructure cible (celle qui va recevoir le dépôt définitif) et d’y importer le dépôt avec son historique.

Après avoir créé le dépôt sur l’infrastructure cible https://git.spip.net/organisation/prefix_du_plugin.git, utiliser les commandes suivantes :

git remote add prefix_du_plugin https://git.spip.net/organisation/prefix_du_plugin.git
git push prefix_du_plugin master 

Note : Si l’historique des commits est bien conservé, les tickets et pull-requests ne sont pas importés, c’est donc à utiliser lorsque que l’import ne fonctionne pas.

21. Comment mettre à jour une mutualisation ?

Avec la mutualisation, la mise à jour par l’interface de SPIP ne convient pas bien car elle met le code dans des sous-dossiers différents pour chaque version, ce qui a pour effet de désactiver le plugin pour les autres sites. Il faut donc faire les mises à jour sans changer le dossier.
OVH propose une méthode : https://mutu.jack31.org/Mutualisation-chez-OVH-on-applique-une-solution-differente mais ça convient pas à tout le monde. Il y a sûrement d’autres solutions encore, mais sinon voici comment faire en ligne de commande (cron ou ssh) et avec git.

Pour installer 1) sur une mutualisation, 2) par ssh ou dans un cron, 3) la dernière version stable du plugin dont l’url du repo est url_remote 4) dans le dossier local_directory 4) et la mettre à jour :

git clone url_remote local_directory
cd local_directory
git fetch --all
git checkout $(git describe --tags --abbrev=0)

Ça copie localement le dernier tag créé, qui est souvent la dernière version stable.
Il y a un message d’avertissement car on arrive dans un état “détaché”, sur un commit qui n’est pas une branche.

22. À quoi servent les dépôts personnels ? Puis-je en créer un pour un plugin spécifique à mon site perso ?

En plus d’accéder aux dépôts des “organisations”, chacun peut se créer des dépôts personnels.
Ces dépôts personnels servent à deux choses :

1. faire des forks pour faire des PR afin de commiter sur les dépots de l’organisation “core”, car tout le monde a les droits requis pour faire des branches pour les plugins de l’organisation “contributions”
2. pour maintenir des plugins communs mais sensibles, qui ne doivent pas pouvoir être modifié à l’arrache pas n’importe qui.

23. Synchroniser un clone et ses branches

Pour faire proprement des PR il faut partir d’un master propre, qui ne contient que les commits du repo d’origine. Pour cela il ne faut jamais commit dessus, et tu le pull avec l’option —rebase pour ne pas avoir de commit de merge dessus non plus.

Ça permet ensuite d’avoir des branches, que tu peux rebase sur le master quand il a été mis a jour, et dont on aura ici que les commits ajoutés (et sans commit de merge)

En local, les lignes suivantes dans le .gitconfig global évitent les commits de merge.

[pull]
	ff = only
	rebase = true

Comment nettoyer et synchroniser un clone crade avec le master ?
-  Sur ton master il faut que tu fasse un git reset 351d3e4a957207b3a2c01c7df9d7cdc9537907b3 pour revenir au dernier commit officiel
-  puis un git reset --hard pour supprimer les modifs
-  puis un git rebase upstream/master ou upstream est le nom du remote qui pointe sur le repo spip/spip officiel.
-  ça ramènera tous les commits du core et tu seras dans les clous à nouveau

Et pour des branches ?
-  si tu as besoin d’autres branches il faut les rebase pareil depuis le core

24. Comment gérer les conflits qui empêchent un merge

Q : « Je dois merger et git me signale des conflits. Que fais je ? »
A : « Tu passes sur le master. tu pull. Ensuite tu bascules sur ta branche de PR et tu fais un git rebase master tabranchedepr. »
Q : « Là il détecte les conflits ... Je les rèsouds et quand c’est bon je fais git rebase --continue. Si je recommence il dit “no rebase in progress” »
A : « Maintenant tu peux balancer un push force de ta branche de PR : git push --force et zou »

25 Mieux que force-push

Utiliser push --force-with-lease --force-if-includes plutôt que push --force

Ça évite d’écraser si quelqu’un·e a fait un commit entre temps

26. Revert un commit

- pour vérifier, voir le diff entre 2 commits : git diff abcdef..123456 (la référence du premier commit, deux petits points et la référence du second commit). Et on ajoute l’option -w pour ne pas voir les changements d’espaces ou de TAB.
-  revert un commit : git revert xxxxxx (avec le numéro du commit à revert )
-  Revert un commit déjà pushé (exemple)

git checkout master
# e3f1e37 est la révision à laquelle on veut revenir
git reset --hard e3f1e37
git push --force origin master

(cf https://newbedev.com/shell-remove-unwanted-commit-git-rebase-code-example)

27. Comment actualiser un fork ?

Indications en anglais : https://stackoverflow.com/questions/7244321/how-do-i-update-a-github-forked-repository/7244456#7244456

git
git tag -a v1.0.0 -m "Nouvelle version 1.0.0"
git push
git push --tags

Si vous voulez, vous pouvez paramétrer votre git pour éviter cette dernière étape : ouvrez votre fichier ~/.gitconfig et assurez vous qu’il y a dedans :

[push]
    default = simple
    followTags = true

Avec ce paramétrage, il suffit de faire :

git tag -a v1.0.0 -m "Version 1.0.0"
git push

28. Comment sont appelées les branches pour SPIP4 ou pour SPIP5 dans les repo de spip-dist ?

Pour certains repos de spip-dist, c’est simple car l’une des branches s’appelle 4.x (avec un ’x’, pas un numéro) tandis que l’autre est 5.x : c’est l’une d’elle qu’il faut retenir selon la version de SPIP désirée. Dans ce cas, les autres branches sont souvent des branches temporaires créées pour un développement particulier en attente de merge.

Pour d’autres repos c’est pas évident de deviner et ça peut être contrintuitif. La page https://git.spip.net/spip/spip/-/snippets/10 doit alors être consultée pour savoir quel est la branche en relation avec SPIP4 ou SPIP5.