--- 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](index.md) — 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](https://gitea.alpinux.org/alpinux.cedrica5l/alpinux-wiki/pulls). 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](../technique/deploiement-wiki.md) | | 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](markdown.md) | | 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. ```bash git fetch origin pull//head:pr- # la branche de la pull request git switch pr- 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 : ```bash git remote add git@gitea.alpinux.org:/alpinux-wiki.git git fetch git switch -c pr- / ``` `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](../technique/deploiement-wiki.md). ```bash 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 : ```bash 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](../technique/deploiement-wiki.md)