Documentation PrestaShop 9 : contribuer sur GitHub et pull requests

Table des matières :

1. Où vit la documentation PrestaShop 9, et pourquoi passer par GitHub (même pour “juste” corriger du texte)
2. Pré-requis reproductibles : versions, outils, et environnement local sans surprises
3. Fork, clone, branches : un workflow GitHub propre pour une PR qui se merge
4. Rédiger une pull request “reviewable” : scope, preuves, tests et CI
5. Spécificités PrestaShop 9 : Symfony 6.4, Twig, hooks, et documentation qui ne ment pas
6. Cycle de vie d’une contribution : review, rebase, conflits, backports et hygiène de branche
7. Checklist opérationnelle avant d’ouvrir votre PR “Documentation PrestaShop 9”

Où vit la documentation PrestaShop 9, et pourquoi passer par GitHub (même pour “juste” corriger du texte)

La documentation PrestaShop 9 n’est pas un PDF figé : c’est un ensemble de sources versionnées (Markdown, exemples de code, snippets, parfois des assets) qui évoluent au même rythme que le core, les modules officiels et l’écosystème. Contribuer via GitHub n’est pas un “process corporate”, c’est le seul moyen propre de lier une correction de doc à un contexte technique (version, commit, issue, PR associée) et donc d’éviter l’effet classique : “la doc dit X, le code fait Y”.

Dans l’écosystème PrestaShop, la doc peut vivre :

• dans le dépôt du core (ex. un répertoire docs/ ou des sections dans le README) ;
• dans un dépôt dédié à la documentation (souvent avec un générateur de site) ;
• dans les dépôts de modules (où la doc est parfois plus “opérationnelle” que celle du core : installation, compatibilités, tests, FAQ) ;
• dans des pages GitHub (Wiki, GitHub Pages), plus rares pour des projets qui veulent versionner strictement.

Avant de modifier quoi que ce soit, commencez par identifier le bon dépôt et la bonne branche cible. Entre forks, miroirs et dépôts historiques, on perd vite du temps (et on ouvre des PR au mauvais endroit). Le minimum est de vérifier l’origine et la légitimité du repo (organisation, badges, activité, tags, releases, SECURITY.md).

Concrètement, sur GitHub, quelques signaux simples vous évitent des erreurs :

• Le dépôt appartient-il à l’organisation attendue (et pas à un fork personnel) ?
• L’onglet Insights montre-t-il une activité cohérente (PR/Issues récents, tags, releases) ?
• Le repo a-t-il des fichiers de gouvernance : CONTRIBUTING.md, CODE_OF_CONDUCT.md, SECURITY.md, LICENSE ?
• Existe-t-il un template de PR/Issue (souvent dans .github/) qui indique le workflow officiel ?

Sur ce point, voyez aussi l’article interne : PrestaShop GitHub : dépôts officiels, vérification et sécurité anti-forks.

GitHub apporte deux choses que la plupart des équipes sous-estiment : (1) la traçabilité (qui a changé quoi, quand, et pourquoi), (2) le contrôle qualité via revue, CI et checks automatiques.

Dans la pratique, la traçabilité GitHub vous donne un avantage très “terrain” : quand vous mettez à jour une page (ou une commande), vous pouvez lier la preuve au même endroit que la correction : une issue expliquant le bug, un commit qui a modifié le comportement, et une PR qui remet la doc à jour. Cela évite aussi les corrections “locales” non partagées (un wiki interne, un Notion, un Google Doc) qui vieillissent sans alertes.

GitHub résume très bien l’intérêt des PR avec une phrase simple : “Pull requests let you tell others about changes you’ve pushed to a branch in a repository on GitHub.” (GitHub Docs — About pull requests).

Pré-requis reproductibles : versions, outils, et environnement local sans surprises

Pour contribuer proprement à la documentation PrestaShop 9, vous devez caler votre environnement sur les contraintes du projet cible : versions PHP, Composer, Node/Yarn, conventions de formatage et éventuels outils de build de doc. C’est exactement le genre de zone grise où le cœur PrestaShop est parfois incohérent : certaines pages parlent encore de versions PHP différentes selon le canal (README vs doc vs CI).

Pour éviter de faire une PR “théorique”, alignez-vous sur ce qui est réellement supporté dans la branche visée, et documentez explicitement vos hypothèses (ex. “Testé sur PHP 8.2 / Node 20”). C’est d’autant plus important pour une documentation d’installation ou d’outillage : ce sont les pages les plus consultées… et celles qui causent le plus d’allers-retours quand elles sont approximatives.

Pour le sujet PHP, l’article interne suivant donne un cadre utile : PrestaShop 9 : versions PHP recommandées et incohérences de documentation.

Un environnement reproductible limite les aller-retours en review. En pratique, Docker est l’option la plus efficace (surtout en équipe), parce qu’elle verrouille la stack (PHP extensions, MariaDB/MySQL, Redis éventuel, etc.) et réduit le “works on my machine”. Si vous avez besoin d’un setup fidèle prod (même topologie, même versions, mêmes volumes), basez-vous sur : Staging PrestaShop : créer un environnement Docker fidèle à la production.

Côté doc elle-même, pensez “reproductible” aussi :

• Prévisualisation Markdown : la plupart des reviewers lisent dans GitHub, mais un rendu local peut détecter des soucis (listes imbriquées, tableaux, ancres, images).
• Cohérence typographique : guillemets, apostrophes, majuscules, ponctuation française — utile si la doc vise aussi un public francophone (agences, intégrateurs).
• Encodage et fins de ligne : respectez .editorconfig s’il existe ; évitez de polluer un diff avec un passage en CRLF.

Côté outillage Git, ne négligez pas la partie “hygiène” :

• Configurez votre identité (user.name / user.email) et, si votre organisation l’exige, la signature GPG ou SSH.
• Installez les hooks locaux s’il y en a (pre-commit, lint, vérification Markdown).
• N’ajoutez jamais de secrets dans un exemple de doc (tokens, endpoints internes, dumps).
• Évitez aussi les données personnelles dans les exemples (emails réels, noms, adresses). Même une doc technique peut circuler longtemps ; mieux vaut utiliser des données factices cohérentes (et, si besoin, des formats réalistes France/UE : code postal, TVA intracommunautaire fictive, etc.).

Si vous travaillez en contexte CI/CD, pensez “SBOM + scan + policy” (article interne utile : PrestaShop : sécuriser APIs et modules avec SBOM, WAF et CI/CD).

Fork, clone, branches : un workflow GitHub propre pour une PR qui se merge

Le workflow standard reste : fork → clone → branche dédiée → commits atomiques → push → pull request. Sur un dépôt très actif, la différence entre une PR mergée en 24h et une PR qui traîne 3 semaines tient souvent à la discipline sur la branche.

Concrètement :

# Fork via GitHub UI, puis :
git clone [email protected]:VOTRE_USER/repo.git
cd repo

git remote add upstream [email protected]:ORGA/repo.git

git fetch --all --prune

git checkout -b docs/ps9-fix-install upstream/<branche-cible>

Deux détails qui font gagner du temps dès le départ :

• Nommez la branche pour ce qu’elle fait (docs/..., documentation/..., fix/...) : le reviewer comprend immédiatement le scope, et vous retrouvez plus vite la PR quand vous revenez dessus deux semaines plus tard.
• Gardez votre fork à jour : avant de démarrer (et avant de pousser), refaites un git fetch upstream puis comparez votre base. Les PR “qui dérivent” coûtent cher à re-review.

La branche cible n’est pas un détail. Pour PrestaShop, vous allez souvent tomber sur des branches du type 9.0.x, 9.1.x, etc. L’idée est de viser la branche maintenue qui correspond à la réalité de production. Le repère le plus clair reste la logique de versionnement. Même si tous les projets ne respectent pas SemVer à la lettre, la définition officielle est un bon contrat mental : “Given a version number MAJOR.MINOR.PATCH, increment the: MAJOR version when you make incompatible API changes…” (Semantic Versioning 2.0.0).

Sur les commits, appliquez une règle simple : un commit = une intention. Sur une doc, ça veut dire : “corriger une procédure”, “mettre à jour une commande”, “ajouter un exemple validé”. Évitez les commits fourre-tout “fix docs” qui mélangent orthographe, refactor d’exemples, et changements de fond.

Un bon test mental : si votre reviewer devait cherry-pick un seul commit (pour backporter, ou pour isoler une correction urgente), est-ce qu’il pourrait le faire sans embarquer des changements de style inutiles ? Si la réponse est non, découpez.

Rédiger une pull request “reviewable” : scope, preuves, tests et CI

Une PR doc n’a pas besoin de PHPUnit pour exister, mais elle doit rester falsifiable. Chaque fois que vous décrivez une commande, une configuration, ou un résultat attendu, fournissez un minimum de preuves : version exacte, output attendu, liens vers le code source concerné, et éventuellement un screenshot quand c’est pertinent (UI/back-office). Dans PrestaShop, beaucoup de docs deviennent fausses non pas par malveillance, mais par dérive : un paramètre a changé, un contrôleur a été migré, une route Symfony a été renommée.

Astuce simple et efficace côté “preuves” : quand vous citez du code GitHub, utilisez un permalink (un lien figé vers un commit précis) plutôt qu’un lien vers une branche. Ça évite le ping-pong “le lien ne pointe plus au bon endroit” quelques mois plus tard, et ça transforme votre PR en référence durable.

Structurez votre PR comme un mini rapport technique :

• Problème (doc incorrecte / manque / ambiguïté)
• Impact (bug d’implémentation, perte de temps, risque sécurité)
• Correction (ce qui change)
• Validation (comment vous avez vérifié)

Exemple de description (format utile même si le repo n’a pas de template) :

Contexte
- PrestaShop 9.1.x, PHP 8.2, Docker
- Page: /docs/…

Problème
- La commande X mentionne --foo alors que l’option est --bar depuis le commit abc123.

Changement
- Mise à jour de la commande + ajout d’un exemple complet.

Validation
- Testé sur une instance neuve (install) et sur une instance existante (upgrade).

Si votre PR touche du code ou des snippets exécutables, déclenchez la CI et faites-la passer. Pour les dépôts qui embarquent des modules, les tests existent souvent mais ne sont pas toujours documentés : si vous devez exécuter PHPUnit dans un module officiel, l’approche Docker est généralement la plus robuste (cf. ps_onepagecheckout : exécuter les tests PHPUnit avec Docker et PrestaShop).

Même sur une PR “doc only”, pensez aux effets de bord :

• Une doc peut casser un build si le repo génère un site (liens cassés, frontmatter manquant, image absente).
• Un exemple de configuration peut induire une mauvaise pratique sécurité si la doc n’est pas prudente (exposer un endpoint admin, désactiver une protection, recommander un droit trop large).

Enfin, évitez l’erreur “doc = changelog”. Une doc explique des usages, des contraintes et des invariants ; le changelog liste des modifications notables. La définition de référence est nette : “A changelog is a file which contains a curated, chronologically ordered list of notable changes for each version of a project.” (Keep a Changelog). Si vous ajoutez une note de version, mettez-la au bon endroit.

Spécificités PrestaShop 9 : Symfony 6.4, Twig, hooks, et documentation qui ne ment pas

PrestaShop 9 renforce l’axe Symfony (services, conteneur DI, contrôleurs plus “framework”), et ça a une conséquence directe sur la documentation : les exemples basés sur l’ancienne architecture finissent par être activement nuisibles.

Le piège classique côté doc : “ça marchait avant, donc je documente pareil”. Or, avec Symfony 6.4 (LTS) et Twig, certains réflexes doivent évoluer :

• documenter l’extension/variation de comportement via services (décoration, configuration) plutôt que “override systématique” ;
• expliciter le contexte : Back-Office Symfony vs contrôleurs historiques, routes, permissions, templates Twig vs Smarty ;
• signaler quand un exemple est compatibilité (fonctionne, mais déconseillé) vs recommandé (maintenable, aligné avec le core).

Par exemple, documenter un override “par réflexe” sans expliquer les limites (compatibilité, maintenance, collisions) pousse des intégrations dans un cul-de-sac. L’article interne sur l’adaptation des modules/thèmes aux contrôleurs services et Twig donne un bon panorama des changements de mentalité : PrestaShop 9 : adapter modules et thèmes aux contrôleurs services et Twig.

La doc doit aussi traiter les hooks avec précision. Dans PrestaShop, les hooks “dynamiques” et leurs patterns peuvent surprendre, et la différence entre un hook stable et un hook dérivé est critique pour un module maintenable.

Une contribution doc utile, ici, ne se contente pas de lister un hook : elle précise au minimum :

• où il s’exécute (Front/Back, page, contrôleur, moment) ;
• ce que le hook reçoit (arguments, contexte) ;
• ce qui est garanti (stabilité, disponibilité) vs ce qui est opportuniste (lié à un template, une route, une variante).

Si votre contribution touche aux hooks (ou à une page qui les mentionne), vérifiez les exemples et citez les contraintes réelles (naming, regex, contexte d’exécution). Référence utile : Hooks PrestaShop : comprendre les hooks dynamiques et les regex.

Dernier point : la doc PrestaShop 9 doit assumer les zones où le core n’est pas “clean”. Exemple typique : certaines optimisations (cache Smarty, CCC, pipeline front) dépendent plus de l’hébergement et de la configuration que du code.

Une doc honnête fait deux choses :

• elle donne une procédure (quoi activer, où, avec quelles limites) ;
• elle propose une méthode de validation (quelles métriques regarder, quoi comparer).

Si vous documentez une optimisation, rattachez-la à des pratiques vérifiables (headers cache, purge, CDN) et pas à des promesses vagues. En interne, vous pouvez vous appuyer sur : PrestaShop : optimiser performance via cache Smarty, CCC et CDN.

Cycle de vie d’une contribution : review, rebase, conflits, backports et hygiène de branche

Une fois la PR ouverte, le plus important est la réactivité et la stabilité du diff. Répondez point par point, citez la doc officielle ou le code source quand un reviewer conteste une formulation, et évitez de “débattre à l’opinion”.

Deux bonnes pratiques simples pendant la review :

• Si un reviewer demande une précision, ajoutez-la dans la doc, puis citez-la dans votre réponse. Une conversation GitHub se perd ; une doc corrigée reste.
• Si vous modifiez une partie sensible (installation, sécurité, compatibilité), reformulez pour être testable : “faites X, vous devez obtenir Y”, plutôt que “en général ça marche”.

Si on vous demande une modification, faites un commit additionnel clair (ou squash si le projet le préfère), mais ne noyez pas la PR sous 15 micro-commits “typo”. Sur des docs, une stratégie efficace est souvent : 1 commit pour le fond, 1 commit pour les corrections demandées (et éventuellement un squash final si demandé).

Sur un repo actif, attendez-vous à rebases fréquents. Le pattern robuste : rebase de votre branche sur upstream/<branche-cible> puis force-push sur votre fork uniquement. Exemple :

git fetch upstream

git checkout docs/ps9-fix-install
# Rebase interactif si vous voulez nettoyer l’historique
git rebase upstream/<branche-cible>

git push --force-with-lease origin docs/ps9-fix-install

--force-with-lease évite d’écraser le travail d’un collègue si vous partagez la branche. C’est le genre de détail qui évite des incidents inutiles (et des discussions stériles).

Enfin, si votre correction doc concerne une fonctionnalité présente sur plusieurs branches maintenues, anticipez le sujet du backport. Les maintainers peuvent vous demander d’ouvrir une PR supplémentaire vers une branche plus ancienne (ou plus récente), ou d’adapter la formulation pour ne pas introduire de confusion.

Faites-le proprement : un cherry-pick ciblé, pas un copier/coller. Et si votre PR reflète un changement de comportement (pas seulement un texte), vous êtes potentiellement sur un sujet “release notes” : assumez la responsabilité de décrire l’impact utilisateur.

Un point d’hygiène souvent oublié : une fois la PR mergée (ou fermée), supprimez la branche de votre fork si elle n’a plus d’intérêt. Ça limite les erreurs futures (repartir d’une vieille branche, pousser au mauvais endroit) et garde votre espace GitHub lisible.

Checklist opérationnelle avant d’ouvrir votre PR “Documentation PrestaShop 9”

Le moyen le plus rapide de perdre du temps est d’ouvrir une PR incomplète, puis de la “finir” en public. Une PR est un artefact de production : elle doit être mergeable, justifiable et testée à un niveau raisonnable. La checklist ci-dessous n’est pas théorique ; elle correspond à ce que les maintainers attendent implicitement sur les projets qui ont un volume de contributions non trivial.

D’abord, vérifiez que votre contribution respecte la réalité d’exécution. Sur PrestaShop, ça veut dire : version exacte (9.0/9.1/9.2…), PHP, mode d’installation (Composer vs archive), et contexte (multiboutique, modules actifs). Si vous documentez une commande CLI ou une config serveur, notez explicitement ce que vous avez utilisé (Docker, Debian/Ubuntu, Nginx/Apache, etc.). Dans le doute, reproduisez dans un staging (voir le lien Docker plus haut) plutôt que sur votre poste.

Ensuite, appliquez la checklist :

• La PR vise la bonne branche et le bon dépôt (sinon elle sera fermée ou ignorée).
• Le diff est minimal (pas de reformatage global, pas de changements de style non demandés).
• Les exemples sont copiables-collables et testés (sorties/erreurs attendues).
• Aucun secret, endpoint privé, dump, email client, ou token dans les exemples.
• Les liens externes sont stables (GitHub Docs, RFC, specs) et les liens internes du dépôt ne cassent pas.
• Si le repo a des checks (lint Markdown, tests, build), ils sont au vert.
• La description de PR explique pourquoi (pas seulement “what”).

Pour rendre la checklist encore plus opérationnelle, voici un dernier contrôle “anti-ambiguïté” qui marche très bien sur de la doc PrestaShop :

• Est-ce qu’un intégrateur peut exécuter la procédure sans vous (sur une machine neuve, en France/UE comme ailleurs) ?
• Est-ce que le texte distingue clairement pré-requis, étapes, résultat attendu, dépannage ?
• Est-ce que vous avez évité les formulations floues (“normalement”, “en principe”) au profit d’invariants testables ?

Si vous faites ce minimum, vous augmentez mécaniquement vos chances de merge, et vous évitez surtout le scénario classique : “PR techniquement bonne mais trop coûteuse à reviewer”. C’est exactement l’objectif quand on contribue à la documentation PrestaShop 9 : réduire la dette d’ambiguïté, pas la déplacer sur l’équipe qui maintient.