Alpinux ce1f58d652 Documenter le poste de mainteneur, et aligner le README sur le wiki

Le README et les pages de contribution se contredisaient : « éditer la
page dans Gitea » ignorait la bifurcation devenue la règle, le tableau
d'aiguillage ne connaissait pas trois des pages existantes, et le délai
de publication n'était pas le même des deux côtés. Le README oriente
désormais, le wiki explique — une seule source de vérité par sujet.

Nouvelle page « Relire et fusionner » : ce que fusionner publie, la
relecture, la vérification du build, les pièges du poste — renommer une
page casse son adresse, aucune redirection n'est installée.

Au passage, trois points où les pages ne se répondaient pas : la
publication immédiate depuis Obsidian ne concerne que le clone du dépôt
du wiki, la bifurcation se remet à jour après chaque fusion, et
l'accueil renvoyait au Markdown générique plutôt qu'à notre page.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01BE4rvHVETRoWnYNDTGssdo

2026-09-19 23:18:36 +02:00

6.7 KiB

Raw Blame History

description
Guide des mainteneurs du wiki Alpinux — relire une pull request, vérifier le build, fusionner, et réparer quand la publication coince.

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.

!!! note "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 :

!!! warning "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.

!!! tip "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.

tail -20 /var/log/wiki-deploy.log      # sur le serveur

!!! info "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 :

grep -rn "ancienne-page" docs/ README.md

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

6.7 KiB Raw Blame History