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
This commit is contained in:
Alpinux
parent
9d2c931a92
commit
ce1f58d652
8 changed files with 214 additions and 14 deletions
33
README.md
33
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.
|
||||
|
|
|
|||
|
|
@ -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.
|
||||
|
||||
</div>
|
||||
|
||||
---
|
||||
|
|
|
|||
|
|
@ -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.
|
||||
|
||||
---
|
||||
|
||||
|
|
|
|||
165
docs/contribuer/mainteneurs.md
Normal file
165
docs/contribuer/mainteneurs.md
Normal file
|
|
@ -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/<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 :
|
||||
|
||||
```bash
|
||||
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](../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)
|
||||
|
|
@ -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 :
|
||||
|
||||
|
|
|
|||
|
|
@ -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)
|
||||
|
||||
|
|
|
|||
|
|
@ -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
|
||||
|
|
|
|||
|
|
@ -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
|
||||
|
|
|
|||
Loading…
Reference in a new issue