From fd3c8b41b4bf26ad858b6ae4f07a2bd5acf8aa60 Mon Sep 17 00:00:00 2001 From: Alpinux Date: Sat, 19 Sep 2026 22:36:36 +0200 Subject: [PATCH] =?UTF-8?q?Faire=20de=20la=20pull=20request=20la=20r=C3=A8?= =?UTF-8?q?gle,=20et=20documenter=20la=20bifurcation?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 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) Claude-Session: https://claude.ai/code/session_01PcZ7hL9aVvMhRuzxXLT2DG --- README.md | 18 +++++---- docs/contribuer.md | 92 ++++++++++++++++++++++++++++++++++------------ 2 files changed, 79 insertions(+), 31 deletions(-) diff --git a/README.md b/README.md index 86fe91e..5be747b 100644 --- a/README.md +++ b/README.md @@ -12,14 +12,17 @@ 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 | 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 | +| Écrire un article, travailler hors ligne | **Bifurquer**, cloner, 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 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](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. +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é. --- @@ -42,9 +45,10 @@ ligne intact plutôt que de le publier à moitié. ### Les deux pièges à connaître -> **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. +> **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. diff --git a/docs/contribuer.md b/docs/contribuer.md index 31aaa8d..eb9a611 100644 --- a/docs/contribuer.md +++ b/docs/contribuer.md @@ -117,6 +117,19 @@ C'est la façon la plus simple de contribuer : corriger une faute, compléter un 10. Cliquez sur **« Proposer la modification »**. +!!! info "Si Gitea vous parle de « bifurcation »" + Selon vos droits sur le dépôt, deux situations : + + - **Vous êtes membre de l'équipe du wiki** : l'éditeur s'ouvre directement et vous + créez une branche dans le dépôt, comme décrit ci-dessus. + - **Vous n'avez pas encore les droits d'écriture** : Gitea vous propose de créer une + **bifurcation** (*fork*), c'est-à-dire votre copie personnelle du dépôt. Acceptez : + votre modification y est enregistrée, et la pull request la propose au wiki. Le + résultat est le même, la copie sert juste de brouillon qui vous appartient. + + Dans les deux cas, vous n'écrivez jamais directement sur le site en ligne : c'est la + fusion de la pull request par un mainteneur qui publie. + --- ## Étape 3b — Proposer un nouvel article @@ -252,17 +265,40 @@ Les mainteneurs peuvent consulter la [procédure de déploiement](technique/depl 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 +La règle est la même que depuis le navigateur : **on ne modifie jamais `main` +directement**. On travaille sur une branche, et on propose son travail par une pull +request. Cela vaut pour tout le monde, mainteneurs compris. + +### 1. Bifurquer, puis cloner + +Créez votre **bifurcation** (*fork*) du wiki : sur +[le dépôt](https://gitea.alpinux.org/alpinux.cedrica5l/alpinux-wiki), bouton +**Bifurcation** en haut à droite. Vous obtenez votre propre copie, dans laquelle vous +pouvez tout faire sans rien risquer. + +Clonez ensuite **votre** copie, et gardez un lien vers le dépôt d'origine pour pouvoir +vous mettre à jour : ```bash -git clone git@gitea.alpinux.org:alpinux.cedrica5l/alpinux-wiki.git +git clone git@gitea.alpinux.org:VOTRE-COMPTE/alpinux-wiki.git cd alpinux-wiki +git remote add upstream git@gitea.alpinux.org:alpinux.cedrica5l/alpinux-wiki.git ``` 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 +### 2. Partir du wiki à jour, sur une branche + +Avant chaque nouveau sujet : + +```bash +git switch main +git pull upstream main # récupérer ce qui a été publié entre-temps +git switch -c sauvegarder-ses-photos # une branche par sujet, au nom parlant +``` + +### 3. Voir le rendu avant de proposer ```bash python3 -m venv venv && source venv/bin/activate @@ -271,27 +307,33 @@ 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 : +meilleur moyen de vérifier un tableau, une image ou un bloc de code. Pour s'assurer que +rien n'est cassé (lien mort, page absente de la navigation) : ```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 +mkdocs build --strict -d /tmp/wiki-build ``` -Gitea affiche alors un lien pour ouvrir la pull request. La suite est identique à -l'[étape 4](#etape-4-ouvrir-la-pull-request). +### 4. Proposer 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. +```bash +git add . +git commit -m "Article : sauvegarder ses photos sur un disque externe" +git push -u origin sauvegarder-ses-photos +``` + +Gitea affiche alors un lien pour ouvrir la pull request vers le wiki. La suite est +identique à l'[étape 4](#etape-4-ouvrir-la-pull-request) : un mainteneur relit, fusionne, +et la publication se fait toute seule. + +!!! warning "Pourquoi ne pas pousser sur `main`" + Un commit qui arrive sur `main` est publié dans la minute, sans relecture et sans + retour en arrière possible autre qu'un nouveau commit. Même quand on en a le droit, + passer par une branche et une pull request donne trois choses : un regard extérieur, + une trace de la discussion, et la possibilité de laisser un texte reposer sans qu'il + soit en ligne. + + Réservez le push direct aux urgences — une information fausse à retirer tout de suite. ### Avec Obsidian @@ -299,11 +341,13 @@ Le dépôt est aussi un coffre [Obsidian](https://obsidian.md) : ouvrez le dossi 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. +L'extension **Obsidian Git** y est installée. Elle commite et pousse sur la branche +courante — donc : + +- **placez-vous sur votre branche de travail** avant d'écrire (`git switch -c mon-sujet`, + ou le sélecteur de branche dans le panneau *Source Control* d'Obsidian) ; +- si vous activez la sauvegarde automatique, elle poussera vos brouillons au fil de la + frappe : c'est confortable sur une branche, et à proscrire sur `main`. ---