Repository navigation
💡 [REQUEST] - Rendre les release notes intelligibles et révéler les manques documentaires #2865
Description
Contexte et source
La relecture de la note 9.27.0 avec un regard de nouvel arrivant révèle des formulations techniques, des liens documentaires incomplets et un besoin de rendre les interventions après mise à jour immédiatement visibles.
Besoin ou résultat attendu
Les notes de version doivent expliquer les changements aux utilisateurs du socle sans exiger la lecture des tickets ni des commits. Chaque changement doit être relié à la documentation pertinente. Les manques documentaires doivent être révélés et suivis jusqu’à correction. Toute intervention nécessaire après mise à jour doit être explicite et visible dans les différents rendus.
Périmètre
Le skill de release notes, ses formats de sortie et ses scénarios d’évaluation. La note 9.27.0 et les publications existantes ne sont pas modifiées.
Références
DĂ©finition du fini
- Les règles éditoriales sont adaptées à une personne découvrant le socle, avec distinction entre droits de consultation et définition non modifiable d’un rôle.
- Le reprovisionnement est expliqué à partir de la configuration déclarative et les noms exacts de l’interface restent identifiables.
- Chaque changement est relié à une documentation pertinente vérifiée ; tout manque, contenu obsolète ou source inaccessible est signalé avec la correction ou vérification attendue.
- Les actions nécessaires après mise à jour sont visibles avant les changements dans chaque rendu et ne sont pas remplacées par une mention générique ; aucune rubrique vide n’est ajoutée sans action requise.
- Les garanties existantes de validation humaine et de non-publication sont préservées.
- Au moins trois scénarios réalistes sont comparés entre la version précédente et le skill candidat dans des contextes isolés, avec vérifications structurelles ciblées.
Activity
StephaneTrebel commentedon Oct 16, 2026
Conception validée : employer « socle » hors libellés exacts, expliquer le reprovisionnement par la configuration déclarative, distinguer droits de consultation et définition de rôle non modifiable, et relier chaque changement à une documentation pertinente vérifiée.
Les lacunes documentaires doivent être signalées avec le changement concerné et la correction attendue, puis rester ouvertes jusqu’à lecture du contenu corrigé. Une source inaccessible reste « Documentation non vérifiée », sans conclure qu’elle manque. Les actions de migration sont placées avant les changements dans tous les rendus ; en l’absence d’action, aucune rubrique ni phrase de réassurance.
Modifications locales préparées sur
docs/release-notes-editorial: skill, contrats source/audit/GitHub/Mattermost et évaluations regroupées dansevals/evals.json; les cinq scénarios antérieurs sont inchangés.Trois nouveaux scénarios comparés entre version précédente et candidat dans des contextes isolés, avec le même modèle et seulement l’outil
read: nominal sans action 6/7 → 7/7 ; migration sous pression 5/6 → 6/6 ; lacunes documentaires 4/6 → 6/6. Les 19 assertions du candidat sont satisfaites. Profil Agent Skills, liens relatifs, JSON, cohérence des contrats, empreintes des sources évaluées et espaces blancs vérifiés. Revue indépendante statique : aucun écart important relevé.Aucun test applicatif, changement de release note publiée ou de documentation externe. Branche locale non encore intégrée ; ticket laissé ouvert.
StephaneTrebel commentedon Oct 16, 2026
MR en brouillon pour validation par l’équipe : #2866. Contrôles ciblés revalidés et 19 assertions comparatives satisfaites. Aucune modification des notes publiées ; aucune fusion effectuée.
docs(release-notes): apply editorial skill to 9.27.0
StephaneTrebel commentedon Oct 16, 2026
Suivi des 10 écarts documentaires détectés pendant la relecture de la Release Note 9.27.0, avec origine, pages concernées, grandes lignes attendues et critères de fini dans chaque ticket :
Les travaux documentaires antérieurs sont référencés : le ticket sur la branche mémorisée suit le contenu annoncé par la PR documentation 113, absent des pages consultées ; le ticket sur la fiche GitLab concerne la publication du contenu déjà présent sur main depuis la PR documentation 114, pas sa réécriture. Les écarts restent ouverts jusqu’à vérification de leur correction sur le site public.