Relire et fusionner — guide du mainteneur¶
Les contributeurs s'arrêtent à la pull request. Ce qui suit — relire, vérifier, fusionner — est le travail des mainteneurs, et c'est ce qui met réellement le wiki en ligne.
Pour qui ?
Pour les membres de l'équipe du wiki, qui ont le droit de fusionner sur main. Si
vous contribuez sans ce droit, votre parcours est décrit dans
Contribuer au wiki — rien de ce qui suit ne vous est demandé.
Ce que fusionner veut dire¶
Fusionner une pull request publie. Le site est reconstruit dans la minute, sans autre
validation, sans bouton à presser. Il n'existe pas d'étape intermédiaire entre votre clic
et https://wiki.alpinux.org.
D'où la seule règle qui compte de ce côté-ci :
On ne pousse pas sur main
Même avec les droits, même pour une faute de frappe : une branche, une pull request, une relecture. Un mainteneur qui court-circuite la règle se relit lui-même — c'est précisément ce que la règle cherche à éviter, et cela prive la contribution de sa trace écrite.
Relire¶
Les pull requests ouvertes sont sur la page Pull requests du dépôt. L'onglet Fichiers modifiés affiche le diff ; on commente une ligne précise en cliquant sur le + dans la marge.
La liste de contrôle¶
| À vérifier | Pourquoi |
|---|---|
La page est déclarée dans nav: de mkdocs.yml |
Sinon le build --strict échoue, ou la page existe sans être atteignable |
Les liens internes visent un fichier .md |
MkDocs les valide au build ; une URL en dur pointe dans le vide après un renommage |
Les images sont sur static.alpinux.org |
Aucune image n'est versionnée ici — voir Déploiement du wiki |
Un seul titre # en début de page |
Le thème en fait le titre de l'onglet et de la navigation |
Le front-matter porte une description |
C'est ce qui s'affiche dans les moteurs de recherche et les aperçus de partage |
| La syntaxe employée fait partie des extensions activées | La référence est Écrire en Markdown |
| Ce qui vieillit est daté | Version de logiciel, tarif, adresse, capture d'écran |
Le fond, ensuite¶
La forme se corrige en une minute ; le fond demande votre attention. Une procédure est-elle reproductible par quelqu'un qui découvre ? Les commandes ont-elles été jouées, ou recopiées d'un autre site ? Un guide qui prétend fonctionner sans avoir été essayé coûte plus cher à l'association qu'une page absente.
Corriger plutôt que renvoyer
Pour une virgule, une coquille, un lien à réparer : corrigez vous-même dans la branche de la pull request et dites-le en commentaire. Renvoyer un contributeur bénévole pour une broutille, c'est souvent le perdre. Gardez les demandes de changement pour ce qui touche au fond.
Vérifier le build avant de fusionner¶
Pour une correction de texte, le diff suffit. Dès qu'une pull request touche
mkdocs.yml, ajoute une page ou déplace un fichier, vérifiez-la en local.
git fetch origin pull/<numéro>/head:pr-<numéro> # la branche de la pull request
git switch pr-<numéro>
mkdocs build --strict -d /tmp/wiki-build
Si ce ref n'existe pas, ajoutez la bifurcation du contributeur comme dépôt distant et récupérez sa branche directement :
git remote add <contributeur> git@gitea.alpinux.org:<contributeur>/alpinux-wiki.git
git fetch <contributeur>
git switch -c pr-<numéro> <contributeur>/<sa-branche>
mkdocs serve donne le rendu réel, utile pour un tableau, un bloc dépliable ou une grille
de cartes. Le -d de build n'est pas optionnel : sans lui, MkDocs écrit dans le
site_dir du serveur.
Fusionner¶
Sur la page de la pull request, bouton Fusionner :
- Créer un commit de fusion pour un travail construit, dont les commits racontent quelque chose ;
- Écraser (squash) pour une suite de « wip », « oups », « re-oups » : le wiki garde une ligne d'historique propre, et le contributeur reste l'auteur du commit.
Cochez la suppression de la branche. Écrivez un message de fusion qui dise ce qui entre dans le wiki — il sera lu dans six mois par quelqu'un qui cherche quand une page a changé.
Puis remerciez en commentaire. Une contribution acceptée en silence est une contribution qu'on n'a qu'une fois.
Après la fusion¶
Rafraîchissez la page publiée moins d'une minute plus tard : elle doit être à jour. Si
elle ne l'est pas, le détail de la chaîne — webhook, service d'écoute, deploy-wiki.sh,
staging — et le journal sont décrits dans
Déploiement du wiki.
Un build qui échoue ne casse rien
Le site n'est remplacé que si mkdocs build --strict réussit. En cas d'échec, la
version précédente reste en ligne et c'est main qui est fautif : corrigez par une
nouvelle pull request, ou revenez en arrière avec git revert.
Les pièges du poste¶
Déplacer ou renommer une page casse son adresse. Aucun plugin de redirection n'est installé : l'ancienne URL renverra un 404, y compris depuis un lien partagé sur Mastodon ou dans un compte-rendu de réunion. Avant de fusionner un renommage, demandez-vous s'il vaut son prix, et cherchez les liens entrants :
Une bifurcation vieillit. Une pull request ouverte il y a trois semaines peut porter
un mkdocs.yml dépassé et écraser la navigation. Le diff le montre : si la page des
fichiers modifiés touche des lignes que personne n'a changées dans cette contribution,
demandez une mise à jour depuis upstream avant de fusionner.
Le webhook est attaché à ce dépôt. Un push ailleurs ne publie rien, quoi qu'en dise l'interface de l'autre dépôt.
Donner les droits¶
L'accès au dépôt passe par AlpID puis par l'équipe du wiki, dans les Paramètres du dépôt sur la forge. Le serveur, lui, ne reçoit aucun droit d'écriture : il tire par une clé de déploiement en lecture seule.
Avant d'ajouter quelqu'un à l'équipe, mesurez ce que vous donnez : le droit de fusionner est le droit de publier. Un contributeur régulier travaille très bien depuis sa bifurcation, aussi longtemps qu'il le souhaite.
Une question ?¶
- En réunion Alpinux, 1er et 3e jeudis du mois
- Dans le salon Matrix de l'association
- Côté technique : Déploiement du wiki