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
|
||||
git add .
|
||||
git commit -m "..."
|
||||
git push # → gitea.alpinux.org:alpinux.cedrica5l/alpinux-wiki
|
||||
```
|
||||
Compter **une minute** entre le push 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é.
|
||||
|
||||
C'est tout : le push suffit. Le webhook déclenche `deploy-wiki.sh` sur le serveur, qui
|
||||
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).
|
||||
### Les deux pièges à connaître
|
||||
|
||||
> Le webhook est attaché à **ce** dépôt. Un push dans l'ancien monorepo
|
||||
> `alpinux.site.2026` ne publie rien.
|
||||
> **Un push sur `main` est une publication.** Pas de relecture, pas d'étape de validation :
|
||||
> 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
|
||||
├── articles/ # Articles longs (hors nav principale)
|
||||
├── 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
|
||||
`static.alpinux.org`. Le logo PNG est généré depuis le SVG par `scripts/build-assets.py`.
|
||||
Aucune image n'est versionnée ici : le logo et les illustrations sont servis depuis
|
||||
`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
|
||||
```
|
||||
|
||||
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
|
||||
|
||||
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/
|
||||
|
|
@ -226,12 +235,78 @@ C'est ce que votre navigateur lit quand vous visitez `https://wiki.alpinux.org`.
|
|||
|
||||
### 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.
|
||||
|
||||
---
|
||||
|
||||
## 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}
|
||||
|
||||
Le Markdown est un format texte très simple. Voici l'essentiel pour rédiger une page wiki.
|
||||
|
|
|
|||
Loading…
Reference in a new issue