AkiGarage/readme-release-sync

Synchronisation README & Release

Utilisez cette compétence dès qu'une tâche touche le texte du README, les notes de version, les changelogs, les captures d'écran/GIFs du produit, ou la documentation bilingue du produit.

L'objectif est de réduire la charge de relecture pour les mainteneurs : la documentation doit correspondre à l'état réel du produit avant que les relecteurs aient à détecter des noms obsolètes, des captures d'écran, des descriptions de fonctionnalités, ou des écarts anglais/japonais.

Règle fondamentale

Ne modifiez pas la documentation destinée aux utilisateurs à partir de la documentation existante uniquement. Identifiez d'abord la source de vérité actuelle : code de l'application, chaînes UI, captures d'écran/GIFs, branche de release, fichiers de version, métadonnées du paquet, ou une capture d'écran/vidéo récente fournie par l'utilisateur.

Workflow

1. Ancrer l'état cible

   • Confirmez le nom du produit/application, la branche, la version, le nom du binaire et le périmètre de plateforme à partir des fichiers du dépôt ou des instructions explicites de l'utilisateur.
   • Inspectez l'implémentation pertinente ou les chaînes UI pour les fonctionnalités décrites.
   • Traitez les captures d'écran/vidéos récentes fournies par l'utilisateur comme une preuve visuelle faisant autorité, sauf si le code ou le contexte de la branche les contredit clairement.

2. Mettre à jour la documentation et les médias ensemble

   • Remplacez les captures d'écran/GIFs obsolètes lorsque l'UI a changé.
   • Vérifiez que chaque référence d'image existe et pointe vers le fichier prévu.
   • Assurez-vous que les captures d'écran ne contredisent pas visuellement le nom actuel du produit, les libellés de menu, la version ou l'état de l'UI.
   • Supprimez les anciennes références médiatiques lorsqu'elles décrivent un comportement supprimé.
   • Pour une release publique alimentée par un dépôt privé, mettez à jour les fichiers README publics dans le dépôt public sur release/vX.Y.Z après que l'instantané épuré y a été copié. Ne vous fiez pas au README privé comme source de vérité publique finale.
   • Traitez le CHANGELOG public, les brouillons de notes de release, la documentation d'installation et les journaux de développement publics comme faisant partie du même ensemble de documents destinés à la release. Ils doivent utiliser les mêmes noms de produit, version, noms d'actifs, mentions de confidentialité et formulation destinée aux utilisateurs que le README.

3. Maintenir l'équivalence de la documentation bilingue

   • Comparez les sections anglaises et japonaises point par point.
   • Conservez les mêmes faits produits, ordre des fonctionnalités, mises en garde et exigences de configuration dans les deux langues.
   • Ne laissez pas un comportement important expliqué dans une seule langue.

4. Rédiger un texte de README public lisible

   • Rendez les sections de première lecture faciles à parcourir : paragraphes courts, une idée par paragraphe, et des lignes vides là où elles améliorent la lisibilité.
   • Commencez par ce que le produit fait et ce que l'utilisateur peut voir ou faire. Placez les détails d'implémentation plus tard, uniquement lorsqu'ils sont importants pour l'installation, la sécurité ou le dépannage.
   • Privilégiez des lignes de comportement claires plutôt que des phrases de fonctionnalités denses. Une bonne structure est un aperçu d'une phrase suivi de 2 à 4 lignes de capacité concises.
   • Pour le comportement UI, décrivez le résultat visible : glisser pour déplacer, redimensionner depuis un bord ou un coin, double-cliquer pour réinitialiser. Évitez les détails internes du framework tels que les zones de détection, les rectangles de curseur, les mécanismes de redimensionnement internes ou les pourcentages par défaut exacts, sauf si l'utilisateur en a besoin.
   • Conservez les informations détaillées là où elles sont réellement utiles, mais ne faites pas porter au README public des explications d'implémentation réservées aux mainteneurs.
   • Appliquez la même règle de lisibilité aux notes de version et aux entrées de changelog : évitez la précision interne comme les pourcentages par défaut exacts, le vocabulaire des zones de détection, les mécanismes de rectangles de curseur ou les détails du système de build, sauf s'ils affectent un correctif visible par l'utilisateur, une étape d'installation ou un chemin de dépannage.

5. Rendre le texte agréable à lire pour les lecteurs japonais

   • Préférez les termes UI japonais courants lorsque c'est naturel : タブ, 詳細パネル, マウスオーバー, 最小表示, フローティングタブ.
   • Conservez les éléments techniques tels que les commandes, les chemins, les noms de paquets, les noms d'applications, les URL et les identifiants de code en anglais.
   • Supprimez les listes de fonctionnalités redondantes et les paragraphes répétés ; rendez l'ensemble principal de fonctionnalités rapidement parcourable pour un lecteur japonais général.

6. Rechercher les dérives de produit obsolètes

   • Anciens noms de produit, anciens noms d'application, anciens noms de binaire et anciens noms de dépôt.
   • Anciens numéros de version en dehors des entrées de changelog historiques.
   • Libellés UI obsolètes, notes de plateforme supprimées et captures d'écran d'un comportement plus ancien.
   • Affirmations qui impliquent qu'une dépendance doit être en cours d'exécution alors que seul un CLI ou un paquet installé est requis.

7. Valider avant de clore

   • Exécutez les commandes de lint/vérification de documentation disponibles.
   • Exécutez un scan rg limité pour les noms/versions/libellés obsolètes.
   • Exécutez le scan de formulation obsolète/privée/trop interne sur les fichiers README, les changelogs, les notes de release et toute documentation publique livrée dans la release, pas seulement le README de premier niveau.
   • Vérifiez que les liens d'image du README existent.
   • Pour les PR de release, fournissez aux mainteneurs les URL de README rendu par GitHub pour la branche/PR et attendez l'approbation visuelle explicite. Cela doit correspondre à l'affichage GitHub que les utilisateurs verront réellement ; les aperçus locaux, le Markdown brut, les captures d'écran statiques ou les vérifications automatisées ne sont que des preuves secondaires.
   • Inspectez le git diff du dépôt public pour que les affirmations du README, les métadonnées de version, les noms d'actifs de release et les modifications d'implémentation copiées concordent.
   • Pour les releases publiques, préférez la branche release/vX.Y.Z -> PR -> CI -> merge avant le tag ou la création de GitHub Release. Les pushs directs sur main ne doivent être utilisés que lorsque le mainteneur demande explicitement de sauter la validation par PR.
   • Si le code a changé, exécutez les tests ou la build pertinents.
   • Résumez les vérifications de source de vérité, pas seulement les fichiers modifiés.

Liste de vérification de sortie

Avant de terminer, signalez :

• nom du produit/version/branche vérifié(e) ;
• références médiatiques vérifiées ;
• parité japonais/anglais vérifiée ;
• approbation visuelle du README rendu par GitHub reçue, ou explicitement toujours en attente ;
• résultat du scan de formulation obsolète ;
• tests/build/vérifications de doc exécutés, ou raison pour laquelle ils n'ont pas été exécutés.