Carnet Wiki

FAQ pratique : Comment SPIPer avec git.spip.net

Version 33 — Février 2021 JLuc

Il y a abondance de tutoriels généraux pour git sur le net et il y en a même un dans la nébuleuse de la galaxie SPIP. Cette page ici n’est donc pas une FAQ générale sur git. Elle ne concerne que git.spip.net et l’usage de git et de la forge git pour SPIP, avec gitea, et seulement cela.

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.

Les parties incertaines et à valider sont en italique.

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

Non : on peut cloner un repo, ou plus simplement juste télécharger son code, sans devoir s’inscrire sur git.spip.net

-  Pour télécharger, on se servira de l’icone « Télécharger » sur la page d’une contribution, à droite des adresses ssh et https (voir copies d’écran ci dessous).

Le téléchargement permet de récupérer le zip de la contribution et de l’installer pour SPIP, mais ce n’est pas un repo 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 repo.

-  Pour cloner : la commande est git clone url_repo, où url_repo est l’adresse https ou ssh du repo (voir ci dessous)

Que sont les adresses ssh et https d’une contribution ?

Un repo peut être accédé par les 2 protocoles ssh et https, et propose donc des urls pour chacun de ces protocoles. Ces 2 urls sont indiquées sur les pages du repo.

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.

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

-  Pour un repo 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 -> prompt de demande du login (pseudo ou mail fonctionnent) -> prompt de demande du mot de passe

-  avec l’url ssh, il faut avoir créé une clé ssh (pour cela, suivre les indications de https://help.github.com/en/github/authenticating-to-github/generating-a-new-ssh-key-and-adding-it-to-the-ssh-agent), et l’avoir déclarée à git.spip : on transfère le contenu de la clé publique dans la configuration du compte : Profil et réglages > Configuration > Clés SSH / GPG. Votre authentification sera ensuite automatique et transparente : plus besoin de mot de passe.

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

Comment informer SVP qu’il y a une mise à jour importante 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 n’y a pas d’interface gitea pour créer un tag et il faut donc le faire par la ligne de commande.

Exemple : pour créer un nouveau tag 1.., se mettre dans le dossier source racine du plugin, et faire :

git tag -a v1.. -m "v1.."
git push
git push --tags

Si vous voulez, vous pouvez paramétrer votre git pour éviter cette dernière étape : ouvrez votre ficheir ~/.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.. -m "Version 1.."
git push

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 utilisateurs une nouvelle version du plugin.

Peut-on effacer un tag ?

S’il d’aventure il vous arrivait de créer un tag puis de changer d’avis, il est possible de le supprimer.

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

Comment paramétrer git en local ?

Une bonne partie de la config proposée par Delicious Insight peut être reprise pour les développements SPIP ainsi que leur prompt (un peu adapté), super utile : https://delicious-insights.com/fr/articles/apprendre-git (dans Installation et Configuration>configuration partagée")

Comment importer sur git.spip.net un plugin développé sur github ou gitlab ?

Il y a 2 manières de faire : en cliquant 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 repo 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épot distant comme dépot 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 »

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 cloner localement 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’usages d’une fonction ou pour corriger tous ces appels.

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

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 https://git.spip.net/user/settings/account

Quelques commandes de base ?

Voir les autres documentations et tutos.

-  revert un commit : git revert xxxxxx (avec le numéro du commit à revert )
-  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 si on ajoute l’option -w ça ignore les changements qui ne sont que des espaces.

Comment 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 forl du repo.

-  Pour proposer une modification sur le core ou un plugin-dist, il faut créer un fork (car, à moins de droits spéciaux, on ne peut pas créer une branche sur le repo d’origine). On pourra ensuite développer sur le master du fork, et faire la PR.

-  Pour proposer une modification sur un plugin, on est pas obligé de forker : il suffit de créer une nouvelle branche. Le nom de cette branche doit évoquer le motif de sa création : inclure le n° de ticket ou un motclé évocateur.

Pour commit, git merge ou merge rebase ?

- Il faut faire du merge rebase.
-  Et donc il ne faut pas faire rebase no ff car ça force le commit de merge par défaut.

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. Sur la logique plus communautaire 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. Du moins pour les plugins, car pour le core et les plugins-dist, il est nécessaire de faire un fork.

Comment actualiser un fork ?

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

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 (Gitea, Gitlab...) 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.

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.

Questions encore sans réponses

...

les Organisations de git.spip.net

Les plugins se trouvent essentiellement dans les « extensions fonctionnelles », encore que certains squelettes (ou thèmes) soient désormais techniquement accessibles sous forme de paquets par SVP...

...

...

...

...

...

...

...
cf. dans cettepage, voir #gitea-mirror..../voir aussi : récuperer le seul source Zip de tout un ensemble..

Retour à la version courante

Toutes les versions