GitRust GitRust
Connexion

Eric / documentation

CONTRIBUTING.md 6301 octets

Contribuer à la documentation gitrust

Bienvenue ! Ce guide explique comment ajouter du contenu, traduire des pages et soumettre une pull request.

1. Choisir le bon type de contenu (Diátaxis)

Avant de créer un fichier, posez-vous la question : qu'est-ce que le lecteur veut faire ?

TypeLe lecteur veut…Dossier cible
TutorielApprendre pas-à-pas, être guidé{manuel}/tutorials/
Guide pratiqueAccomplir une tâche précise{manuel}/how-to/
RéférenceTrouver une information technique{manuel}/reference/
ExplicationComprendre le pourquoi, le contexte{manuel}/explanation/

Consultez CLAUDE.md pour les règles Diátaxis strictes appliquées à ce dépôt. Aucun fichier de contenu ne doit exister hors des quatre dossiers ci-dessus (dans chaque manuel).

2. Ajouter une page

  1. Créez le fichier Markdown dans le bon dossier selon Diátaxis.
  2. Ajoutez une entrée dans src/SUMMARY.md à la bonne position hiérarchique.
  3. Rédigez en français (langue source canonique).
  4. Respectez la checklist pédagogique ci-dessous pour les tutoriels.

Checklist pédagogique pour les tutoriels

Chaque tutoriel doit cocher toutes ces cases avant d'être fusionné :

  • Objectifs Bloom observables déclarés en tête (O1..On) avec des verbes d'action (lister, exécuter, configurer, diagnostiquer, comparer, concevoir) — interdits : comprendre, maîtriser, savoir, connaître, se familiariser avec
  • Prérequis explicites : technique (outils/versions), pédagogique (tutoriel précédent complété), temps estimé
  • Modèle mental ou schéma Mermaid installé avant la première commande
  • Pas plus de 3 concepts nouveaux dans la page
  • Pas plus de 2 étapes consécutives sans checkpoint observable
  • Sortie console attendue affichée verbatim après chaque commande
  • Section « Et si ça ne marche pas » avec au moins 3 erreurs fréquentes et leur correction
  • Récapitulatif qui reprend explicitement chaque objectif (Oi)
  • Lien vers la prochaine étape du parcours

3. Workflow de traduction

La documentation source est en français. Les traductions passent exclusivement par les fichiers po/. Langues cibles : en (prioritaire), de, es, pt, it.

3.1 Installation (une seule fois)

cargo install mdbook-i18n-helpers   # fournit mdbook-xgettext et mdbook-gettext
sudo apt install gettext            # fournit msginit et msgmerge (Debian/Ubuntu)

Activer ensuite dans book.toml le preprocessor [preprocessor.gettext] (décommenter le bloc).

3.2 Extraction initiale des chaînes (.pot)

MDBOOK_OUTPUT='{"xgettext": {"pot-file": "messages.pot"}}' mdbook build -d po

Produit po/messages.pot — le template maître contenant toutes les chaînes du FR source.

3.3 Initialiser une langue (première fois)

msginit --no-translator -i po/messages.pot -l en -o po/en.po
# répéter pour de, es, pt, it

3.4 Resynchroniser après modification du FR

Quand une page .md source change, régénérer .pot puis fusionner dans chaque .po sans perdre les traductions existantes :

MDBOOK_OUTPUT='{"xgettext": {"pot-file": "messages.pot"}}' mdbook build -d po
for lang in en de es pt it; do
  msgmerge --update po/$lang.po po/messages.pot
done

3.5 Modifier une traduction

Éditer le fichier po/{lang}.po avec un éditeur gettext (recommandé : Poedit ou extension VSCode gettext).

Format d'une entrée :

#: src/introduction.md:3
msgid "Phrase en français"
msgstr "Translated phrase"

Ne jamais modifier un fichier .md pour traduire — tout passe par po/.

3.6 Builder une version localisée

MDBOOK_BOOK__LANGUAGE=en mdbook build -d book/en
# ou toutes les langues d'un coup :
./scripts/build-all-langs.sh

Les chaînes non traduites (msgstr vide) tombent en fallback sur le FR source.

4. Conventions Mermaid

  • Les sources Mermaid sont des fichiers .mmd dans diagrams/.

  • Un fichier .mmd = une source de vérité. Ne jamais dupliquer un diagramme dans plusieurs pages .md.

  • Dans les pages .md, insérer le diagramme via un bloc de code Mermaid :

    ```mermaid
graph LR
    A --> B
```

  • Pour les diagrammes partagés entre plusieurs pages, inclure le contenu du .mmd (copie explicite acceptable, mais documenter la source dans un commentaire).

  • Valider tout .mmd avant de soumettre :

    mmdc -i diagrams/mon-diagramme.mmd -o /tmp/test.svg

5. Règles Markdown

Ce dépôt utilise markdownlint-cli2 avec la configuration .markdownlint.yaml.

Règles notables :

  • Longueur de ligne max : 120 caractères (MD013)
  • HTML autorisé : <details>, <summary> (MD033)
  • La première ligne d'un fichier n'a pas besoin d'être un H1 (MD041 désactivé, car mdBook injecte le titre)
  • Les titres suivent une hiérarchie stricte sans saut de niveau (MD001)

Lancer le lint localement :

markdownlint-cli2 "**/*.md"

6. Synchronisation avec le dépôt source gitrust

Ce dépôt est autonome : tout contenu issu de gitrust/docs/ a été copié ici et ne dépend plus du dépôt source. Quand gitrust évolue (nouvelles variables d'environnement, nouveaux endpoints API, changements d'architecture), une synchronisation manuelle est nécessaire :

  1. Comparer les fichiers sources dans gitrust/docs/ avec leurs copies dans ce dépôt.
  2. Mettre à jour les pages concernées.
  3. Documenter le changement dans le message de commit (sync: mise à jour depuis gitrust vX.Y).

7. Workflow de pull request

  1. Créez une branche depuis main : git checkout -b doc/ma-contribution
  2. Faites vos modifications, lancez mdbook build et markdownlint-cli2 "**/*.md" localement.
  3. Ouvrez une PR sur demo.gitrust.eu/gitrust/girust_doc.
  4. La CI vérifie : build mdBook, lint Markdown, validation des .mmd.
  5. Un relecteur vérifie la checklist pédagogique (pour les tutoriels) et la cohérence Diátaxis.
  6. Fusion en squash merge après approbation.