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