diff --git a/README.md b/README.md index 9c3399b..f116aa8 100644 --- a/README.md +++ b/README.md @@ -3,7 +3,13 @@ Documentation, guides et ressources du LUG Alpinux — Savoie. Accessible sur `https://wiki.alpinux.org`. -Construit avec **MkDocs Material**. Les sources sont des fichiers Markdown ; le site HTML est généré **sur le serveur**, à chaque push sur `main`. +Construit avec **MkDocs Material**. Les sources sont des fichiers Markdown ; le site HTML +est généré **sur le serveur**, à chaque fois que des commits arrivent sur `main` — c'est-à-dire +à chaque pull request fusionnée. + +> Ce fichier s'adresse à qui ouvre le dépôt. Les procédures de contribution, elles, vivent +> dans le wiki lui-même et n'ont qu'un seul endroit où être à jour : +> **[Contribuer au wiki](https://wiki.alpinux.org/contribuer/)**. --- @@ -11,10 +17,13 @@ Construit avec **MkDocs Material**. Les sources sont des fichiers Markdown ; le | Ce que vous voulez faire | Ce que vous faites | Détail | |---|---|---| -| Corriger une faute, mettre à jour une info | Éditer la page dans Gitea, ouvrir une **pull request** | [Contribuer](https://wiki.alpinux.org/contribuer/) | -| Écrire un article, travailler hors ligne | **Bifurquer**, cloner, une branche par sujet, pull request | [Rédiger en ligne de commande](https://wiki.alpinux.org/contribuer/ligne-de-commande/) | -| Rédiger dans Obsidian | Ouvrir le clone comme coffre — il est déjà configuré — sur une branche | idem | -| Relire et publier une contribution | Fusionner la pull request : la publication suit | ci-dessous | +| Avoir un compte pour contribuer | Créer un **AlpID**, puis se connecter à la forge | [Le Git d'Alpinux](https://wiki.alpinux.org/guides/git-alpinux/) | +| Corriger une faute, mettre à jour une info | Éditer la page depuis le navigateur — Gitea crée votre **bifurcation** au passage — puis **pull request** | [Modifier une page](https://wiki.alpinux.org/contribuer/#etape-modifier-une-page) | +| Écrire un article | **Bifurquer**, la remettre à jour, une branche par sujet, pull request | [Proposer un nouvel article](https://wiki.alpinux.org/contribuer/#etape-nouvel-article) | +| Travailler hors ligne | Cloner sa bifurcation, `upstream` vers ce dépôt, rendu local | [Rédiger en ligne de commande](https://wiki.alpinux.org/contribuer/ligne-de-commande/) | +| Rédiger dans Obsidian | Ouvrir le clone comme coffre — il est déjà configuré — sur une branche | [Rédiger avec Obsidian](https://wiki.alpinux.org/contribuer/obsidian/) | +| Retrouver une syntaxe Markdown | Consulter la référence des extensions réellement activées ici | [Écrire en Markdown](https://wiki.alpinux.org/contribuer/markdown/) | +| Relire et publier une contribution | Relire, vérifier le build, fusionner : la publication suit | [Guide du mainteneur](https://wiki.alpinux.org/contribuer/mainteneurs/) | | Comprendre pourquoi ça n'est pas en ligne | Lire le journal de déploiement sur le serveur | [Déploiement du wiki](https://wiki.alpinux.org/technique/deploiement-wiki/) | **Personne n'a de build à lancer ni de fichier à copier sur le serveur.** Publier, c'est @@ -23,6 +32,10 @@ fusionner une pull request : le contenu arrive sur `main`, le reste est automati > **La pull request est la règle, pour tout le monde.** On ne modifie pas `main` > directement, même quand on en a le droit : c'est ce qui permet la relecture, garde une > trace des discussions, et laisse le temps à un texte de reposer avant d'être publié. +> +> Sans droit d'écriture sur ce dépôt, on travaille dans sa **bifurcation** (*fork*) — sa +> copie personnelle — et la pull request part de là. C'est le cas le plus courant, et +> Gitea le propose de lui-même dès qu'on édite une page. --- @@ -39,7 +52,7 @@ deploy-wiki.sh : git pull → mkdocs build --strict → staging rsync vers le DocumentRoot Apache ──▶ https://wiki.alpinux.org ``` -Compter **une minute** entre le push et la page à jour. Le build passe par un répertoire +Compter **moins d'une minute** entre la fusion et la page à jour. Le build passe par un répertoire de staging : une erreur — lien mort, page absente de la navigation — laisse le site en ligne intact plutôt que de le publier à moitié. @@ -99,6 +112,9 @@ mkdocs build --strict -d /tmp/wiki-build > Le `-d` est nécessaire en local : le `site_dir` de `mkdocs.yml` pointe vers le > DocumentRoot Apache du serveur, pas vers un chemin local. +Le déroulé complet — bifurcation, `upstream`, branche, rendu local, pull request — est +décrit dans [Rédiger en ligne de commande](https://wiki.alpinux.org/contribuer/ligne-de-commande/). + --- ## Déploiement serveur (ISPConfig) @@ -115,5 +131,6 @@ Le wiki est servi statiquement par Apache via ISPConfig : Ce dépôt se suffit à lui-même : `~/Projects/alpinux.wiki`, rien à cloner à côté. -Pour les autres projets de l'association (les applications Flask, le CDN, l'infra) et -leurs procédures de déploiement : `~/Projects/org.alpinux.owni/README.md`. +Pour les autres projets de l'association : `~/Projects/org.alpinux.owni/README.md` sert +d'index. Ceux qui ont leur propre dépôt — `alpinux.admin`, `alpinux.dynamic` — décrivent +leur déploiement dans leur propre README. diff --git a/docs/contribuer/index.md b/docs/contribuer/index.md index ee6435f..698d7fb 100644 --- a/docs/contribuer/index.md +++ b/docs/contribuer/index.md @@ -252,9 +252,9 @@ C'est ce que votre navigateur lit quand vous visitez `https://wiki.alpinux.org`. ### 4. Délai de publication -**Quelques secondes.** Personne n'a de bouton à presser : dès que votre pull request est -fusionnée, Gitea prévient le serveur, qui récupère les sources et reconstruit le site. -Rafraîchissez la page une minute plus tard, votre texte y est. +**Moins d'une minute.** Personne n'a de bouton à presser : dès que votre pull request +est fusionnée, Gitea prévient le serveur, qui récupère les sources et reconstruit le +site. Rafraîchissez la page une minute plus tard, votre texte y est. Si le build échoue — un lien mort, une page absente de la navigation — **rien n'est mis en ligne** : le site reste dans son état précédent, et c'est la version fautive qui attend @@ -285,6 +285,11 @@ Une fois le mécanisme compris, trois pages pour approfondir : Le dépôt est un coffre Obsidian prêt à l'emploi : réglages, publication depuis l'éditeur, et le piège de la sauvegarde automatique. +- :material-check-decagram: **[Relire et fusionner](mainteneurs.md)** + + Pour l'équipe du wiki : relire une pull request, vérifier le build, fusionner — + et ce que ça publie. + --- diff --git a/docs/contribuer/ligne-de-commande.md b/docs/contribuer/ligne-de-commande.md index a0e5276..31a1a06 100644 --- a/docs/contribuer/ligne-de-commande.md +++ b/docs/contribuer/ligne-de-commande.md @@ -134,11 +134,15 @@ Retour des install parties : en dessous de 4 Go, Cinnamon rame. ```bash git switch main git pull upstream main +git push origin main # votre bifurcation reste à jour git branch -d sauvegarder-ses-photos # la branche a fait son travail git push origin --delete sauvegarder-ses-photos ``` -Garder ses branches fusionnées ne sert à rien et finit par encombrer la liste. +Garder ses branches fusionnées ne sert à rien et finit par encombrer la liste. Le +`git push origin main` évite l'écueil décrit dans +[Proposer un nouvel article](index.md#etape-nouvel-article) : une bifurcation qu'on +laisse vieillir repart d'une version dépassée au sujet suivant. --- diff --git a/docs/contribuer/mainteneurs.md b/docs/contribuer/mainteneurs.md new file mode 100644 index 0000000..8b9775d --- /dev/null +++ b/docs/contribuer/mainteneurs.md @@ -0,0 +1,165 @@ +--- +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) diff --git a/docs/contribuer/obsidian.md b/docs/contribuer/obsidian.md index e115cce..fdaab31 100644 --- a/docs/contribuer/obsidian.md +++ b/docs/contribuer/obsidian.md @@ -84,7 +84,10 @@ lancez `mkdocs serve` en parallèle. ## Travailler sur une branche C'est le point à retenir : **Obsidian Git commite et pousse sur la branche courante**. -Si cette branche est `main`, chaque sauvegarde publie en ligne, sans relecture. +Si votre coffre est un clone du dépôt du wiki et que cette branche est `main`, chaque +sauvegarde publie en ligne, sans relecture — c'est la situation des mainteneurs. Depuis +une bifurcation, le risque est moindre : vous ne poussez que chez vous. Dans les deux +cas, la règle ne change pas — **une branche par sujet, puis une pull request**. Avant d'écrire, placez-vous donc sur votre branche de travail. Deux façons : diff --git a/docs/index.md b/docs/index.md index f0cae9b..cb369b7 100644 --- a/docs/index.md +++ b/docs/index.md @@ -53,7 +53,9 @@ Ici vous trouverez des guides pratiques, des comptes-rendus de présentations et ## Contribuer Ce wiki est collaboratif : tout membre peut proposer une modification ou un nouvel article. -Les pages sont écrites en [Markdown](https://www.markdownguide.org/basic-syntax/) et hébergées sur notre [Gitea](https://gitea.alpinux.org). +Les pages sont écrites en [Markdown](contribuer/markdown.md) et hébergées sur +[le Git d'Alpinux](guides/git-alpinux.md). Chaque contribution passe par une pull request, +relue avant publication. [:octicons-arrow-right-24: Guide de contribution pas à pas](contribuer/index.md) diff --git a/docs/technique/deploiement-wiki.md b/docs/technique/deploiement-wiki.md index 3ab5523..c2bc2de 100644 --- a/docs/technique/deploiement-wiki.md +++ b/docs/technique/deploiement-wiki.md @@ -10,6 +10,9 @@ Cette page décrit comment mettre en ligne une nouvelle version du wiki après a Cette procédure s'adresse aux mainteneurs ayant accès SSH au serveur `alpinux.org`. Les contributeurs n'ont rien à faire : leur travail s'arrête à la pull request. + Le versant éditorial du rôle — relire une contribution, vérifier le build, fusionner + — est décrit dans [Relire et fusionner](../contribuer/mainteneurs.md). + --- ## Vue d'ensemble diff --git a/mkdocs.yml b/mkdocs.yml index d493a1d..ad14798 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -67,6 +67,7 @@ nav: - Écrire en Markdown: contribuer/markdown.md - Rédiger en ligne de commande: contribuer/ligne-de-commande.md - Rédiger avec Obsidian: contribuer/obsidian.md + - Relire et fusionner (mainteneurs): contribuer/mainteneurs.md - Alpinux: - alpinux/index.md - FAQ: alpinux/faq.md