Dire explicitement qui fait quoi pour publier
Le README annonçait « le push suffit » sans dire à qui cela s'adressait, et la page Contribuer décrivait une publication manuelle en 24 à 48 heures — ce qui n'a jamais correspondu au webhook, et plus du tout depuis qu'il fonctionne. README : un tableau « je veux… » qui relie chaque intention à son geste et à la page qui le détaille, le trajet d'un commit jusqu'à la mise en ligne, et les deux pièges — un push sur main publie sans relecture, et le webhook n'écoute que ce dépôt. contribuer.md : le délai réel (quelques secondes) et le filet du staging, plus une section « Rédiger depuis son ordinateur » — clone, aperçu local, branche et pull request, coffre Obsidian — qui n'était documentée nulle part alors que c'est la façon dont le wiki est rédigé au quotidien. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01PcZ7hL9aVvMhRuzxXLT2DG
This commit is contained in:
Alpinux
parent
aa5948ab9c
commit
dd60bacf54
2 changed files with 119 additions and 19 deletions
57
README.md
57
README.md
|
|
@ -7,25 +7,47 @@ Construit avec **MkDocs Material**. Les sources sont des fichiers Markdown ; le
|
||||||
|
|
||||||
---
|
---
|
||||||
|
|
||||||
## Flux de publication
|
## Je veux…
|
||||||
|
|
||||||
|
| 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 | Cloner le dépôt, **une branche par sujet**, pull request | [Rédiger depuis son ordinateur](https://wiki.alpinux.org/contribuer/#rediger-depuis-son-ordinateur) |
|
||||||
|
| Rédiger dans Obsidian | Ouvrir ce dossier comme coffre — il est déjà configuré | idem |
|
||||||
|
| Relire et publier une contribution | Fusionner la pull request : la publication suit | ci-dessous |
|
||||||
|
| 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
|
||||||
|
faire arriver du contenu sur la branche `main` de ce dépôt — que ce soit par une pull
|
||||||
|
request fusionnée ou par un push direct.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Ce qui se passe une fois sur `main`
|
||||||
|
|
||||||
```
|
```
|
||||||
Modifier → git commit → git push → webhook Gitea → git pull + mkdocs build sur le serveur
|
main (Gitea)
|
||||||
|
│ webhook ──▶ service d'écoute sur le serveur (signature vérifiée)
|
||||||
|
▼
|
||||||
|
deploy-wiki.sh : git pull → mkdocs build --strict → staging
|
||||||
|
│
|
||||||
|
│ build réussi ? ── non ──▶ le site en ligne reste tel quel
|
||||||
|
▼ oui
|
||||||
|
rsync vers le DocumentRoot Apache ──▶ https://wiki.alpinux.org
|
||||||
```
|
```
|
||||||
|
|
||||||
```bash
|
Compter **une minute** entre le push et la page à jour. Le build passe par un répertoire
|
||||||
git add .
|
de staging : une erreur — lien mort, page absente de la navigation — laisse le site en
|
||||||
git commit -m "..."
|
ligne intact plutôt que de le publier à moitié.
|
||||||
git push # → gitea.alpinux.org:alpinux.cedrica5l/alpinux-wiki
|
|
||||||
```
|
|
||||||
|
|
||||||
C'est tout : le push suffit. Le webhook déclenche `deploy-wiki.sh` sur le serveur, qui
|
### Les deux pièges à connaître
|
||||||
construit le site dans un répertoire de staging et ne le met en ligne que si le build a
|
|
||||||
réussi. La procédure complète, et quoi faire quand le webhook ne répond pas, sont
|
|
||||||
décrites dans [Déploiement du wiki](docs/technique/deploiement-wiki.md).
|
|
||||||
|
|
||||||
> Le webhook est attaché à **ce** dépôt. Un push dans l'ancien monorepo
|
> **Un push sur `main` est une publication.** Pas de relecture, pas d'étape de validation :
|
||||||
> `alpinux.site.2026` ne publie rien.
|
> le site est reconstruit dans la foulée. Les brouillons vont sur une branche. Cela vaut
|
||||||
|
> aussi pour la sauvegarde automatique d'Obsidian Git, qui commite et pousse toute seule.
|
||||||
|
|
||||||
|
> **Le webhook est attaché à ce dépôt.** Un push dans l'ancien monorepo
|
||||||
|
> `alpinux.site.2026`, qui a longtemps hébergé le wiki, ne publie plus rien.
|
||||||
|
|
||||||
---
|
---
|
||||||
|
|
||||||
|
|
@ -44,11 +66,14 @@ décrites dans [Déploiement du wiki](docs/technique/deploiement-wiki.md).
|
||||||
├── overrides/ # Surcharges du thème Material
|
├── overrides/ # Surcharges du thème Material
|
||||||
├── articles/ # Articles longs (hors nav principale)
|
├── articles/ # Articles longs (hors nav principale)
|
||||||
├── code/ # Exemples de code référencés dans le wiki
|
├── code/ # Exemples de code référencés dans le wiki
|
||||||
└── scripts/ # Scripts utilitaires (build-assets.py)
|
├── scripts/ # Scripts utilitaires (build-assets.py)
|
||||||
|
└── .obsidian/ # Réglages du coffre Obsidian (partagés)
|
||||||
```
|
```
|
||||||
|
|
||||||
Les images des articles ne sont pas versionnées : elles sont hébergées sur
|
Aucune image n'est versionnée ici : le logo et les illustrations sont servis depuis
|
||||||
`static.alpinux.org`. Le logo PNG est généré depuis le SVG par `scripts/build-assets.py`.
|
`static.alpinux.org`, les pages y pointent par leur URL complète. `scripts/build-assets.py`
|
||||||
|
sert à fabriquer les fichiers du logo à y téléverser quand le SVG source change — il ne
|
||||||
|
tourne pas au déploiement.
|
||||||
|
|
||||||
---
|
---
|
||||||
|
|
||||||
|
|
|
||||||
|
|
@ -21,7 +21,16 @@ sur AlpID à Gitea la page acceptent au
|
||||||
pull request contribution
|
pull request contribution
|
||||||
```
|
```
|
||||||
|
|
||||||
En résumé : vous proposez une modification, un mainteneur la valide, et le wiki se met à jour automatiquement.
|
En résumé : vous proposez une modification, un mainteneur la valide, et le wiki se met à
|
||||||
|
jour tout seul — en quelques secondes, sans intervention de personne.
|
||||||
|
|
||||||
|
!!! note "Deux façons de contribuer"
|
||||||
|
Ce guide décrit la voie **depuis le navigateur**, celle qui ne demande aucune
|
||||||
|
installation et convient à une correction ponctuelle.
|
||||||
|
|
||||||
|
Si vous rédigez régulièrement, la voie **depuis votre ordinateur** (dépôt cloné,
|
||||||
|
éditeur Markdown ou Obsidian) est décrite en fin de page :
|
||||||
|
[Rédiger depuis son ordinateur](#rediger-depuis-son-ordinateur).
|
||||||
|
|
||||||
---
|
---
|
||||||
|
|
||||||
|
|
@ -216,7 +225,7 @@ Vous n'avez pas à vous en préoccuper : il suffit d'écrire du Markdown valide.
|
||||||
|
|
||||||
### 3. Les fichiers sont déployés
|
### 3. Les fichiers sont déployés
|
||||||
|
|
||||||
Le dossier `site/` généré est copié dans le répertoire servi par Apache :
|
Le dossier généré est copié dans le répertoire servi par Apache :
|
||||||
|
|
||||||
```
|
```
|
||||||
/var/www/clients/client1/web2/web/wiki-static/
|
/var/www/clients/client1/web2/web/wiki-static/
|
||||||
|
|
@ -226,12 +235,78 @@ C'est ce que votre navigateur lit quand vous visitez `https://wiki.alpinux.org`.
|
||||||
|
|
||||||
### 4. Délai de publication
|
### 4. Délai de publication
|
||||||
|
|
||||||
La publication n'est pas instantanée : un mainteneur doit déclencher le build après la fusion de votre PR. En pratique, les nouveaux articles apparaissent **dans les 24 à 48 heures** suivant la fusion.
|
**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.
|
||||||
|
|
||||||
|
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
|
||||||
|
une correction. Vous ne risquez donc pas de casser le wiki en vous trompant.
|
||||||
|
|
||||||
Les mainteneurs peuvent consulter la [procédure de déploiement](technique/deploiement-wiki.md) pour les détails techniques.
|
Les mainteneurs peuvent consulter la [procédure de déploiement](technique/deploiement-wiki.md) pour les détails techniques.
|
||||||
|
|
||||||
---
|
---
|
||||||
|
|
||||||
|
## Rédiger depuis son ordinateur {#rediger-depuis-son-ordinateur}
|
||||||
|
|
||||||
|
Pour un article long, une série de corrections ou un travail hors connexion, il est plus
|
||||||
|
confortable de travailler sur une copie locale du wiki.
|
||||||
|
|
||||||
|
### Récupérer le wiki
|
||||||
|
|
||||||
|
```bash
|
||||||
|
git clone git@gitea.alpinux.org:alpinux.cedrica5l/alpinux-wiki.git
|
||||||
|
cd alpinux-wiki
|
||||||
|
```
|
||||||
|
|
||||||
|
Le dépôt contient les pages (`docs/`), les articles longs (`articles/`), les exemples de
|
||||||
|
code cités dans le wiki (`code/`) et la configuration du site (`mkdocs.yml`).
|
||||||
|
|
||||||
|
### Voir le rendu avant de publier
|
||||||
|
|
||||||
|
```bash
|
||||||
|
python3 -m venv venv && source venv/bin/activate
|
||||||
|
pip install mkdocs-material
|
||||||
|
mkdocs serve
|
||||||
|
```
|
||||||
|
|
||||||
|
Ouvrez `http://localhost:8000` : la page se recharge à chaque enregistrement. C'est le
|
||||||
|
meilleur moyen de vérifier un tableau, une image ou un bloc de code avant de proposer
|
||||||
|
quoi que ce soit.
|
||||||
|
|
||||||
|
### Proposer vos modifications
|
||||||
|
|
||||||
|
Comme depuis le navigateur, le travail passe par une branche et une pull request :
|
||||||
|
|
||||||
|
```bash
|
||||||
|
git switch -c mon-article # une branche par sujet
|
||||||
|
git add .
|
||||||
|
git commit -m "Article : sauvegarder ses photos sur un disque externe"
|
||||||
|
git push -u origin mon-article
|
||||||
|
```
|
||||||
|
|
||||||
|
Gitea affiche alors un lien pour ouvrir la pull request. La suite est identique à
|
||||||
|
l'[étape 4](#etape-4-ouvrir-la-pull-request).
|
||||||
|
|
||||||
|
!!! warning "Pousser sur `main` publie immédiatement"
|
||||||
|
Les mainteneurs peuvent pousser directement sur `main`. Dans ce cas il n'y a ni
|
||||||
|
relecture, ni filet : le site est reconstruit dans la minute. Pour un brouillon,
|
||||||
|
utilisez une branche.
|
||||||
|
|
||||||
|
### Avec Obsidian
|
||||||
|
|
||||||
|
Le dépôt est aussi un coffre [Obsidian](https://obsidian.md) : ouvrez le dossier cloné
|
||||||
|
comme coffre, les réglages et extensions sont déjà versionnés (mise à jour automatique
|
||||||
|
des liens internes, et *Linter* pour la mise en forme).
|
||||||
|
|
||||||
|
L'extension **Obsidian Git** y est installée. Si vous activez sa sauvegarde automatique,
|
||||||
|
retenez bien ce qu'elle implique : chaque sauvegarde est un commit poussé sur la branche
|
||||||
|
courante — donc, sur `main`, une publication en ligne. Rédigez vos brouillons sur une
|
||||||
|
branche, ou laissez la sauvegarde automatique désactivée et poussez quand le texte est
|
||||||
|
prêt.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
## Écrire en Markdown {#ecrire-en-markdown}
|
## Écrire en Markdown {#ecrire-en-markdown}
|
||||||
|
|
||||||
Le Markdown est un format texte très simple. Voici l'essentiel pour rédiger une page wiki.
|
Le Markdown est un format texte très simple. Voici l'essentiel pour rédiger une page wiki.
|
||||||
|
|
|
||||||
Loading…
Reference in a new issue