Alpinux fd3c8b41b4 Faire de la pull request la règle, et documenter la bifurcation

La page supposait partout que le contributeur a les droits d'écriture sur le
dépôt : l'option « créer une branche et ouvrir une pull request » de l'éditeur
Gitea n'apparaît que dans ce cas, et la procédure locale poussait une branche
directement sur le dépôt. Quelqu'un d'extérieur à l'équipe tombait sur une
bifurcation sans savoir ce que c'était.

Les deux parcours sont donc repris autour de la bifurcation, et la pull request
est présentée comme la règle pour tout le monde, mainteneurs compris — avec la
raison plutôt que l'injonction : relecture, trace des discussions, et le droit
de laisser un texte reposer sans qu'il soit déjà en ligne. Le push direct est
ramené à ce qu'il doit être, un geste d'urgence.

La procédure locale gagne les étapes qui manquaient : remote upstream, mise à
jour de main avant de créer une branche, build --strict avant de proposer. Et
pour Obsidian, se placer sur sa branche avant d'écrire, puisque la sauvegarde
automatique pousse sur la branche courante.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01PcZ7hL9aVvMhRuzxXLT2DG

2026-09-19 22:36:36 +02:00

4.8 KiB

Raw Blame History

wiki.alpinux.org

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.

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
Écrire un article, travailler hors ligne	Bifurquer, cloner, une branche par sujet, pull request	Rédiger depuis son ordinateur
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
Comprendre pourquoi ça n'est pas en ligne	Lire le journal de déploiement sur le serveur	Déploiement du wiki

Personne n'a de build à lancer ni de fichier à copier sur le serveur. Publier, c'est fusionner une pull request : le contenu arrive sur main, le reste est automatique.

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é.

Ce qui se passe une fois sur `main`

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

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é.

Les deux pièges à connaître

Un commit sur main est une publication. Pas de relecture, pas d'étape de validation : le site est reconstruit dans la foulée. D'où la règle ci-dessus — les brouillons vivent sur une branche. Attention en particulier à la sauvegarde automatique d'Obsidian Git, qui commite et pousse toute seule sur la branche courante.

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.

Structure des sources

.
├── mkdocs.yml          # Configuration MkDocs (nav, thème, plugins)
├── docs/               # Pages Markdown
│   ├── index.md
│   ├── alpinux/        # Présentation, FAQ, événements
│   ├── guides/         # Guides pratiques (Linux Mint, Docker, chiffrement…)
│   ├── presentations/  # Supports de présentations passées
│   ├── technique/      # Documentation technique (déploiement, serveur…)
│   └── communication/
├── 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)
└── .obsidian/          # Réglages du coffre Obsidian (partagés)

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.

Développement local

python3 -m venv venv && source venv/bin/activate
pip install mkdocs-material
mkdocs serve
# → http://localhost:8000  (rechargement automatique à chaque modification)

Pour vérifier que le build est propre (liens, structure) avant de pousser :

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.

Déploiement serveur (ISPConfig)

Le wiki est servi statiquement par Apache via ISPConfig :

DocumentRoot : /var/www/clients/client1/web2/web/wiki-static
Let's Encrypt SSL activé
Aucun service à redémarrer après un déploiement

Voir aussi

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.

4.8 KiB Raw Blame History