Guide Nouvelle Release

Mettre à jour une nouvelle release documentaire

Guide pratique pour préparer une nouvelle release IBM, lancer son extraction, comparer le nouveau JSON avec le JSON de référence conservé dans le cache, contrôler les écarts et valider la mise à jour du corpus Assistant z/OS.

Comparaison JSON N / N+1 Extraction & contrôle du delta Version 1.0

1. Objectif

Une nouvelle release documentaire ne doit pas être chargée aveuglément. Le principe est de produire un nouveau corpus JSON, de le comparer au corpus de référence de la release précédente, puis de valider le delta avant toute mise à jour de la base.

Principe : le JSON conservé dans le cache sert de point de comparaison et de trace technique entre deux releases.

2. Préparer la release N+1

Identifier la nouvelle documentationVérifier le produit, la release, la source IBM et le périmètre documentaire à traiter.

Isoler les sourcesConserver séparément les documents de la release N et ceux de la release N+1.

Préparer l'extractionUtiliser les mêmes règles de traitement que pour le corpus de référence afin que la comparaison reste pertinente.

3. Conserver le JSON de référence N

Avant la nouvelle extraction, conserver le JSON validé de la release actuellement en service. Ce fichier devient la référence de comparaison.

cache/produit/release_N.json

Traçabilité : ne pas écraser le JSON N tant que la release N+1 n'a pas été extraite, comparée et validée.

4. Extraire la release N+1

Lancer l'extracteur sur la nouvelle documentation avec les règles habituelles du pipeline documentaire. Les erreurs d'extraction doivent être journalisées et contrôlées avant la comparaison.

Source IBM identifiée

Release enregistrée

Identifiants techniques extraits

Log d'erreurs contrôlé

5. Générer le JSON N+1

Le résultat de l'extraction est écrit dans un nouveau fichier JSON sans remplacer la référence précédente.

cache/produit/release_N_plus_1.json

Le format et les clés utilisées pour identifier les références doivent rester compatibles avec le JSON N afin de permettre une comparaison fiable.

6. Comparer les JSON N et N+1

Le comparateur rapproche les entrées des deux corpus à partir de leur identifiant technique. Il détermine ensuite le statut de chaque référence.

JSON NCorpus validé actuellement en référence.

JSON N+1Nouveau corpus issu de l'extraction.

ComparaisonRapprochement par identifiant et contenu.

DeltaAdded, Modified, Removed, Unchanged.

ValidationContrôle avant mise à jour.

7. Classer les écarts

Statut	Signification	Traitement
ADDED	Présent uniquement dans N+1.	Nouvelle référence à contrôler.
MODIFIED	Présent dans les deux releases mais contenu différent.	Comparer les champs modifiés.
REMOVED	Présent dans N mais absent de N+1.	Vérification obligatoire avant toute suppression.
UNCHANGED	Référence identique.	Aucune action documentaire nécessaire.

Important : un statut REMOVED ne doit jamais provoquer automatiquement une suppression en production. Une absence peut provenir d'un changement de documentation, de structure ou d'une extraction incomplète.

8. Contrôler les différences

Le delta doit être analysé avant import. Les volumes anormaux ou les changements inattendus doivent conduire à vérifier l'extraction et la source documentaire.

AjoutsVérifier que les nouvelles références appartiennent bien à la release N+1.

ModificationsIdentifier précisément les champs et sections documentaires modifiés.

SuppressionsConfirmer dans la documentation IBM qu'il s'agit d'une disparition réelle.

9. Valider avant import

Contrôler le nombre total de références N et N+1.
Examiner le nombre de ADDED, MODIFIED, REMOVED et UNCHANGED.
Analyser le log d'erreurs de l'extraction.
Vérifier un échantillon des modifications dans la documentation source.
Valider explicitement le delta avant chargement.

Règle : si le delta paraît incohérent, conserver la release N en service et reprendre l'extraction N+1.

10. Charger et archiver

Après validation, le corpus N+1 peut être chargé selon le processus d'import prévu. Les fichiers ayant servi à la décision doivent être conservés pour audit et reprise.

JSON N archivé

JSON N+1 validé

Rapport de comparaison conservé

Logs d'extraction conservés

11. Reprise et rollback

La conservation du JSON N permet de revenir au dernier corpus validé si un problème est découvert après la préparation de N+1. Le rollback doit suivre les procédures techniques de l'environnement et ne doit pas être déclenché automatiquement par le comparateur.

Objectif : toujours pouvoir expliquer quelle release a été extraite, quel delta a été observé et quel corpus a finalement été validé.

12. Gérer les JSON EN, FR IBM et FR traduit

Chaque sous-système peut disposer de plusieurs fichiers JSON selon la langue et l’origine documentaire. Cette séparation évite de mélanger la documentation IBM officielle avec une traduction produite par Assistant z/OS.

EN IBMJSON extrait directement de la documentation IBM anglaise. Il constitue la référence principale pour la comparaison de release.

FR IBMJSON extrait de la documentation IBM française lorsqu’une version française officielle existe pour le même périmètre.

FR traduitJSON issu d’une traduction produite par le pipeline Assistant z/OS lorsque la documentation IBM française n’est pas disponible.

Convention de nommage recommandée

<produit>_<langue>_<origine>_<release>.json

Exemple	Signification
`mq_en_ibm_10.0.json`	Documentation IBM MQ anglaise, release 10.0.
`mq_fr_ibm_10.0.json`	Documentation IBM MQ française officielle, release 10.0.
`racf_fr_translated_3.1.json`	Traduction française produite par Assistant z/OS à partir du corpus RACF anglais.

Règle de comparaison

Une comparaison de release doit toujours opposer des fichiers de même langue et de même origine documentaire.

mq_en_ibm_9.4.json ↔ mq_en_ibm_10.0.json mq_fr_ibm_9.4.json ↔ mq_fr_ibm_10.0.json

Important : ne pas comparer directement un JSON FR IBM avec un JSON FR traduit. Leur origine documentaire est différente, même si la langue est identique.

Organisation du cache

cache-V1/ cics_en_ibm_<release>.json cics_fr_ibm_<release>.json db2_en_ibm_<release>.json db2_fr_ibm_<release>.json ims_en_ibm_<release>.json jes2_en_ibm_<release>.json racf_en_ibm_<release>.json uss_en_ibm_<release>.json

Migration progressive : les fichiers JSON existants du cache peuvent être conservés tels quels pendant la mise en place de cette convention. CICS et DB2 pourront être régénérés à la fin afin d’adopter le nouveau nommage sans interrompre les travaux en cours.

13. Bonnes pratiques

Ne jamais écraser le JSON de référence avant validation.

Comparer des structures JSON compatibles.

Conserver les logs d'erreurs d'extraction.

Contrôler particulièrement les REMOVED.

Valider le delta avant toute mise à jour de la base.

Archiver les JSON et le rapport de comparaison.