Générateur de Module Patch

Introduction

Les patchs mis à disposition pour une version de JCMS / JPlatform sont inévitables et même souvent bienvenus, mais leur déploiement et leur gestion peuvent présenter certains problèmes :

• Comment s'assurer que tel patch, important voire obligatoire (un patch de sécurité par exemple), est effectivement installé dans mon application (sans avoir à analyser le système de fichiers) ?
• Comment assurer (autrement que par des moyens "visuels") que le patch que j'installe est bien compatible avec ma version de JCMS / JPlatform ?
• Comment assurer que des patchs ne sont pas en conflit entre eux, et le cas échéant, qu'un patch "englobant" est bien appliqué après ceux qu'il "englobe" ? Les patchs étant en général constitués de façon indépendante les uns des autres par la R&D Jalios (voire par le Support), ils peuvent en effet modifier des fichiers identiques de façons différentes... La résolution d'un tel conflit sort du cadre de cet article, mais la détection de conflit et, si possible, l'application en connaissance de cause de tel patch après tel autre, doit pouvoir être assuré lors du déploiement de patchs.

Un certain niveau de réponse à ces interrogations est apporté par la notion de Module Patch, tel que défini dans le paragraphe 4.3 de la fiche (Restricted access link) : l'idée est de constituer un module qui va contenir l'ensemble des patchs voulus, en documentant autant que possible son contenu afin de disposer, dans l'IHM d'administration du module, de la liste des patchs concernés.

La construction "manuelle" d'un module patch est cependant particulièrement lourde, car en plus de l'extraction des différentes archives des patchs (les fichiers patch_*.zip) à effectuer à un même endroit, il faut "remplir" le fichier plugin.xml avec toutes les informations nécessaires, notamment la liste exhaustive des fichiers constitutifs de ces patchs, et, éventuellement, la documentation. L'ajout, et pire encore la suppression, d'un patch à un module déjà existant, rajoute un degré de complexité supplémentaire.

Le script (Perl) présenté ici propose de faciliter la constitution de ce module, en ayant simplement, à la limite (facilement atteignable), à déclarer les archives des patchs à inclure dans le module !

Il est utilisé depuis quelques mois avec succès par nos propres équipes, que ce soit celle gérant ce site, Jalios Community, que les consultants des Services Professionnels sur leurs projets respectifs.

Nous espérons que le confort apporté par ce script permettra d'élargir l'adoption de cette notion de "Module Patch" à l'ensemble de nos clients, "desserrera le frein" bloquant trop souvent l'application des patchs, et facilitera en général la maintenance des applications.

Objectifs du script

• Faciliter l'intégration de patchs au sein d'une application (webapp), en constituant automatiquement un Module Patch (cf. le chapitre 4.3 de la fiche Application de patch), à partir d'archives de patchs.
• Vérifier s'il existe des conflits au sein de plusieurs patchs. Un "conflit" existe lorsqu'un même fichier source est embarqué par au moins deux patchs, avec des contenus différents.
• Constituer automatiquement le plugin.xml, sur la base d'un modèle, un "template", fichier indépendant du script comportant les parties statiques et dynamiques (sous forme de pseudo-variables), ces dernières étant "remplies" par le script.
• Gérer les versions, que ce soit celles des patchs (compatibilité avec JCMS / JPlatform), que celle du Module Patch lui-même (les patchs apparaissant le long de la vie d'une même version JCMS / JPlatform, et étant intégrés au fur et à mesure dans les webapps, un Module Patch doit pouvoir avoir plusieurs versions).

Installation

Il suffit d'extraire le contenu de l'archive dans un répertoire quelconque.

L'archive peut être trouvée ici : (Restricted access link)  

Contenu de l'archive :

• makePluginPatch.pl : le script lui-même ; il a été écrit en Perl
• pluginTemplate.xml : un modèle de plugin.xml (aka plugin template), à modifier selon les besoins (voir plus loin)
• changeLog.txt : les évolutions du script en fonction de ses versions successives.

Bien entendu, il faut également disposer d'une version de Perl (celle d'ActiveState en général sous Windows).

Premiers pas

Ce chapitre décrit comment constituer facilement votre premier Module Patch, en un minimum de manipulations, à partir de patchs réels ne présentant pas de conflits.

Scénario

Nous disposons d'une application MyWeb tournant avec JCMS 9 SP4.

Les patchs des issues JCMS-5683, JCMS-5712 et JCMS-5725 doivent y être appliqués sous forme d'un Module Patch.

Nous supposons que le Générateur de Module Patch a déjà été installé, dans le répertoire C:\Jalios\Tools\PatchPluginGenerator (sous Windows donc, mais le fonctionnement est identique sous Linux) :

Etape 1 : Création d'un répertoire de travail

La génération impliquant des fichiers et répertoires à créer, nous allons travailler dans un répertoire dédié. Autant le nommer comme l'application visée, par exemple donc C:\Jalios\Applications\MyWeb\Patches

Etape 2 : Récupération des patchs

Nous téléchargeons chaque patch (ceux correspondant à la version 9.0.4), et les plaçons dans le répertoire de travail :

Etape 3 : Invite de commandes

Nous ouvrons une "Invite de  commandes" (Command Prompt), et nous plaçons dans le répertoire de travail :

Etape 4 : Lancement de la commande

Commande à exécuter : C:\Jalios\Tools\PatchPluginGenerator\makePluginPatch.pl -name MyWebPatches *.zip

Cette commande va construire un Module Patch nommé (techniquement) MyWebPatches.

Nous supposons ici que l'extension .pl a été associée à l'exécutable perl. Si ce n'est pas le cas, insérer perl au début de la ligne de commande, voire (s'il n'est pas dans le "PATH") le chemin complet vers cet exécutable.

Etape 5 : Voilà !

Résultat :

Le répertoire de travail contient désormais :

• Une archive MyWebPatches_1.0.zip, i.e. le Module Patch lui-même pouvant être intégré à l'application ;
• Un sous-répertoire "temporaire" MyWebPatches_1.0, contenu du Module Patch, à partir duquel le zip a été constitué.

Voici le Module Patch (une fois déployé) et sa documentation, tels qu'ils se présentent dans l'IHM d'Administration des Modules (les noms des issues sont des liens référençant les pages JIRA respectives) :

Bien entendu, des options permettent de mieux contrôler ce qui est généré, notamment le libellé, l'auteur, la "licence", les langues dans lesquelles la description du Module sera disponible, le fait de conserver ou non le répertoire "temporaire", etc.

Principe général de fonctionnement

Ce chapitre décrit le fonctionnement complet du script :

• Télécharger les patchs nécessaires à la webapp, et les placer - de préférence - dans un même répertoire local.
• Lorsque le script est lancé, les archives des patchs fournis en argument sont vérifiées, afin de déterminer si leurs versions sont cohérentes entre elles :
  
  • Les numéros de version apparaissent dans les nom des archives, et peuvent avoir plusieurs formes, selon celui qui a constitué l'archive, p.ex. jcms-9.0.4 ou jcms904 pour les patchs patch_JCMS-5712_jcms904.zip ou patch_JCMS-5725_jcms-9.0.4.zip ; le script gère ces variantes.
  • Si un patch concerne plusieurs issues, p.ex. (fictif) patch_JCMS-5712_JCMS-5725_jcms904.zip, le script gère aussi cela, et considère que l'issue "englobante" est la dernière apparaissant dans la liste, les autres étant considérées comme des "sous-issues", et reportées en tant que telles (i.e. indentées sous l' "englobante") dans la description du module.
  • Si un patch comporte plusieurs versions, p.ex. jcms903_jcms904, le script reconnaît cela, et constitue la liste maximale de versions compatibles communes à tous les patchs spécifiés.
    
    • Si tous les patchs spécifiés sont compatibles avec, p.ex., les versions 9.0.3 et 9.0.4 (et même si certains d'entre eux sont compatibles aussi avec d'autres versions), le module généré sera compatible avec ces deux versions.
    • Si aucune version compatible, commune à tous les patchs, ne peut être déterminée, le script s'arrête en erreur (cas p.ex. d'un patch compatible avec une 9.0.3, et d'un autre compatible avec 9.0.4 seulement).
• Ensuite, les contenus des archives sont examinés, afin de déterminer s'il existe des conflits (un même fichier présent dans plusieurs patchs).
  • S'il existe des conflits, tous les conflits sont affichés, et le script s'arrête.
  • Si les fichiers en conflit sont identiques (critères de comparaison : même taille et même signature MD5), le script ne génère qu'un warning pour ce "conflit".
  • Pour résoudre un conflit, c'est ailleurs : voir si on peut se passer d'un patch, en parler à la R&D, etc., jusqu'à ce que le conflit n'existe plus.
  • Si l'un des patchs en conflit a été spécifié après l'option "-force" (parce que l'on sait que l'on peut l'appliquer après tel ou tel autre patch), le conflit sera reporté en warning, et le contenu de ce patch viendra écraser ses fichiers "concurrents". Si plusieurs patchs sont en "-force", ils seront appliqués dans leur ordre d'apparition sur la ligne de commande.
  • Voir le chapitre "Conflits" plus loin pour plus de détails.
• "Détection des conflits seulement" :
  • Si l'option "-d" (pour "-detectConflicts") a été spécifiée, le script s'arrête ici : seule la détection des conflits a été réalisée. Aucun module n'est généré (il n'est pas nécessaire dans ce cas de spécifier le nom du Module Patch dans la ligne de commande), aucune écriture sur disque n'est effectuée.
  • Sinon, on continue :
• Le numéro de version trouvé sert à constituer l'expression régulière qui sera placée dans le plugin.xml, afin de rendre le Module Patch compatible uniquement avec cette dernière.
  • Si cette expression régulière ne peut être produite, le script affiche une erreur et s'arrête.
  • Si plusieurs versions "compatibles" ont été trouvées (voir plus haut), l'expression régulière contiendra un "OU" entre toutes ces versions.
• Génération du fichier plugin.xml : voir plus loin le chapitre dédié à ce sujet.
• Constitution de la structure du Module Patch.
  • Création des répertoires requis pour un module, et placement du plugin.xml dans le bon répertoire
  • Le répertoire temporaire "racine" porte le nom du module à construire. Ce répertoire ne doit pas exister avant l'exécution du script (qui s'arrête en erreur le cas échéant) ; renommer s'il le faut le répertoire existant, et relancer le script.
    • Toutefois, si l'option "-removeTempBefore" est présente, ce répertoire sera effacé s'il existait. Option à utiliser avec grande précaution, car si le nom du patch a été mal spécifié, et qu'il désigne un répertoire important existant, ce dernier sera supprimé sans avertissement !

• Extraction des fichiers des patchs dans la structure.
• Génération de l'archive du Module Patch, à partir de la structure.
  • Le nom de cette archive est constitué du nom du Module Patch, suivi de son numéro de version, puis .zip
  • Le répertoire contenant la structure est conservé, pour éventuelle vérification et/ou mémoire.
• Si l'option "-removeTempAfter" a été spécifiée, et le script s'est déroulé jusqu'au bout sans erreur, le répertoire temporaire est supprimé à la fin.

Génération du fichier plugin.xml

Le fichier modèle (voir dans le chapitre "Ligne de commande", comment il peut être spécifié) est utilisé, et ses "pseudo-variables" vont être remplacées par ce que le script a pu trouver, à partir des archives et des "extra infos" notamment.

Bien entendu, si une valeur précise est spécifiée dans le fichier modèle, au lieu de la pseudo-variable concernée, c'est cette valeur précise qui sera utilisée (sans tenir compte donc de la configuration et de la ligne de commande) ; pratique pour définir un template propre à un projet !

Les informations relatives à un patch peuvent être déclarées dans un fichier (optionnel) d' "extra infos", portant le même nom de fichier que le patch, mais avec .txt pour extension (à la place de .zip) ; voir le chapitre dédié aux "extra infos", plus loin.

"Pseudo-variables"

Notes concernant ces "pseudo-variables" :

• zzJCMS_VERSIONzz : le nom de base (JCMSou JPlatform) est spécifié dans la variable $Config (nommée "Configuration" dans ce document) du script (tout début du fichier), entrée ProductBaseName. Une valeur possible pour une "version" pourra donc être JCMS 9 SP4, ou JPlatform 10 SP1.
• Ce nom de base dépend de la version : JCMS pour les versions 9, JPlatform pour les versions 10 et supérieures (mapping déclaré dans le script, et extensible en rajoutant les déclarations nécessaires dans la variable de Configuration).
• LANG correspond à l'identifiant d'une langue, à l'instar de ceux utilisés dans JPlatform, mais EN MAJUSCULES dans le cadre du script : FR, EN, DE, etc. donc par exemple (exception : lorsqu'une option -xxx_lang est utilisée dans la ligne de commande, la casse n'est pas significative).
• La "Description" du module (zzPLUGIN_DESC_LANGzz) est construite en listant, pour chaque langue définie dans le template, l'ensemble des patchs concernés, en générant pour chacun d'entre eux un hyperlien :
  • par défaut vers l'issue JIRA correspondante (l'URL générique pour cela étant spécifiée dans l'entrée JiraIssueUrl de $Config, cette dernière utilisant la pseudo-variable zzJIRA_ISSUE_IDzz, qui sera remplacée successivement par l'identifiant de chaque issue) ;
  • ou vers l'URL définie dans les extra infos pour ce patch.

"Webapp-files"

Les fichiers constitutifs des patchs sont enfin listés de façon exhaustive dans la section webapp-files, précédés d'un commentaire indiquant de quel patch ils proviennent ; par exemple (capture obtenue depuis l'éditeur Notepad++, qui colorise les fichiers XML) :

Voir ci-dessous, dans le chapitre "Gestion des conflits", les cas particuliers de génération de ces webapp-files, lorsque des conflits ("forcés") ou des fichiers identiques entre patchs sont détectés.

Gestion des conflits

Conflits

Si deux patchs possèdent des fichiers identiques (avec des contenus différents), cela constitue un conflit, et empêche par défaut de constituer le Module Patch. Le script reporte alors cela de la façon suivante (tous les conflits, et même les identifiants d'issues, reportés dans cette documentation ne sont pas forcément réels ; ils peuvent avoir été générés de façon artificielle, à des fins d'illustration) :

De façon générale, si "ERROR." apparaît, cela arrête le script et empêche la génération du Module Patch.

Il est possible que plus de deux patchs soient concernés par un même conflit, auquel cas le script constitue les listes maximales de patchs concernés, afin de faire son rapport :

Si de tels conflits sont détectés, remonter cela au Support Jalios, qui étudiera avec la R&D la façon de les "résoudre", dans la mesure du possible.

S'il est connu (information obtenue auprès de la R&D Jalios ou du Support, d'un Partenaire, etc.), que l'un des patchs inclut ("englobe") les autres, et qu'il peut donc être appliqué après ces derniers, il suffit d'utiliser l'option -force en le déclarant, auquel cas les conflits seront signalés en "warning (forced)"' et n'empêcheront plus la génération du Module Patch.

Par exemple : perl makePluginPatch.pl MyPatch -author "Jalios Support" -license "Free" -removeTempAfter -removeTempBefore patch_*.zip -force patch_SECURITE-20170502_jcms-904.zip

Le plugin.xml généré va alors indiquer, dans sa section webapp-files, les fichiers qui ont été remplacés (i.e. qui sont "overwritten") par leurs équivalents dans un autre patch. Pour cela, il place ces fichiers dans un commentaire, en précisant quel patch les a "remplacés" ; par exemple :

Fichiers identiques

Les fichiers identiques entre plusieurs patchs sont reportés sous forme de "warnings"' ; ils n'empêchent pas de générer le Module Patch.

Deux fichiers (portant bien entendu le même chemin/nom) sont considérés "identiques" si les critères suivants, portant sur les fichiers décompressés, sont égaux :

• Taille en octets
• Signature MD5

Par exemple (apparaissant juste après les éventuels conflits dans la console) :

Dans ce cas, le fichier plugin.xml reporte cet état de fait en plaçant en commentaire, dans sa section webapp-files, les fichiers d'un patch identiques à un autre, i.e. au patch "gagnant" qui va les déclarer effectivement (le patch "gagnant" étant celui qui apparaît en dernier dans la ligne de commande ; en cas d'utilisation de caractères joker, cela dépend du système d'exploitation, mais correspond en général à l'ordre alphabétique ou ASCII des noms des fichiers patchs...) ; le commentaire contient en plus la mention "same as one declared in...".

Par exemple :

Patchs et "extra infos"

Pour constituer le Module Patch et plus particulièrement le plugin.xml, le script a besoin des informations suivantes pour tout patch spécifié sur la ligne de commande :

• L'identifiant du patch ; correspond en général à celui de l'issue JIRA concernée
• La ou les versions de JCMS / JPlatform avec lesquelles il est compatible

Les informations suivantes ne sont pas obligatoires, mais constituent un plus (pour la documentation) :

• Une URL valide référençant sa page de documentation (peut dépendre de la langue)
• Le libellé du patch (dépend de la langue)

Autres informations :

• Pour un patch cumulatif (et un patch de sécurité le plus souvent), les identifiants des issues incluses
• Une petite information supplémentaire, indiquant par exemple qui a généré le patch, ou sa version (si des versions successives ont dû être constituées) ; elle apparaîtra à la suite du libellé du patch, entre parenthèses, dans la description du Module Patch.

Le nom du fichier patch

La plupart de ces informations sont en général obtenues directement depuis le nom du fichier patch (.zip) lui-même :

• Patch simple : patch_JCMS-5725_jcms904.zip
  • Identifiant et libellé dans toutes les langues : JCMS-5725
  • Version compatible : JCMS 9 SP4
  • URL (obtenue grâce à la propriété JiraIssueUrl de la configuration du script) : http://issues.jalios.com/browse/JCMS-5725
• Patch cumulatif : patch_JCMS-6283_JCMS-6378_JCMS-6575_jcms1000.zip
  • Identifiant et libellé dans toutes les langues : JCMS-6283_JCMS-6378_JCMS-6575
  • Version compatible : JPlatform 10
  • URL (par convention, celle de l'issue apparaissant en dernier) : http://issues.jalios.com/browse/JCMS-6575
  • Identifiants des issues incluses :
    • JCMS-6283 (son URL sera aussi générée)
    • JCMS-6378 (son URL sera aussi générée)
• Patch avec information supplémentaire : patch_JCMS-5412_jcms904_support.zip
  • Identifiant et libellé dans toutes les langues : JCMS-5412
  • Version compatible : JCMS 9 SP4
  • Information supplémentaire : support (signifie par convention que le patch a été constitué par le Support Jalios)
• Patch avec plusieurs versions de JCMS compatibles : patch_JCMS-6487_jcms904_jcms1000.zip
  • Identifiant et libellé dans toutes les langues : JCMS-6487
  • Versions compatibles : JCMS 9 SP4 et JPlatform 10

Dans certains cas, ces informations ne peuvent pas être obtenues à partir du nom du fichier :

• Certains patchs ne comportent pas d'identifiant d'issue ; c'est le cas en général des patchs de sécurité.
  • Le script s'arrête alors en erreur (il ne trouve rien qui "ressemble" à un - ou plusieurs si patch cumulé - identifiant(s) d'issue.
  • Dans ce cas, on pourrait renommer le nom du fichier en constituant un identifiant fictif, qui ressemblerait à un identifiant d'issue, par exemple SECURITE-20170502, et c'est ce que nous faisions dans les versions précédentes du script. Mais alors :
• L'URL du patch, constituée à partir de l'identifiant, n'existe pas.
  • Pour le cas décrit précédemment de SECURITE_20170502, cela formerait l'URL http://issues.jalios.com/browse/SECURITE_20170502, qui n'existe pas (de plus, l'URL se trouve en réalité dans le site Jalios Community...)

Pour ces différentes raisons, et d'autres (nécessité par exemple de mieux gérer les langues, ou de documenter les issues constitutives d'un patch de sécurité), la notion d' extra infos" a été introduite.

Les Extra Infos

Toutes les informations décrites ci-dessus peuvent être déclarées dans un fichier texte optionnel, qui doit être situé dans le même répertoire et porter le même nom que l'archive zip concernée, en remplaçant .zip par .txt

La syntaxe de ce fichier est similaire à celle des fichiers de propriétés JPlatform. Les commentaires sont autorisés ; ils doivent être préfixés par le caractère dièse, # ; tout ce qui suit sur la ligne sera alors ignoré par le script.

Lors de la génération du plugin.xml, afin de déterminer la valeur effective d'une propriété, le script essaie de faire "au mieux" : si cette propriété est présente dans les extra infos, elle est utilisée ; sinon le plus souvent, le nom du fichier du patch est mis à contribution pour cela.

Propriétés disponibles :

Ligne de commande

L'option -h permet d'obtenir la liste exhaustive des options disponibles.

Nous décrivons ici les plus notables :

perl makePluginPatch.pl -name <plugin name> [-d] [-label_fr "Mon Patch"] [-v(ersion) <plugin version>]
                        [-t(emplate) <template file>] <zip patchs> ([-f])...

• plugin name : Nom technique du Module Patch a construire.
  • Un sous-répertoire portant ce nom sera créé dans le répertoire d'où la commande a été lancée.
  • L'archive aura ce nom pour préfixe, suivi du numéro de version (et .zip).
  • Si une archive portant le même nom que celle à produire existe déjà, cette dernière se voit attribuer un suffixe, i.e. un compteur qui va être incrémenté de 1 en 1, jusqu'à trouver un nom n'existant pas (p.ex. PatchJC_1.3_1.zip, au lieu de PatchJC_1.3.zip déjà existant dans le répertoire courant).
• -d (ou -detectConflicts) : Pour faire la détection de conflits seulement.
• -f (ou -force) : Pour forcer l'application des patchs qui suivent sur la ligne de commande, dans leur ordre d'apparition.
• -label_fr : Pour spécifier le libellé en français du Module Patch (bien entendu, -label_en est aussi disponible, et en général tout -label_lang, à partir du moment où la balise <label> correspondant à cette langue est définie dans le template)
• -v (ou -version) : Permet de spécifier le numéro de version du Module Patch
  • Si ce numéro n'est pas fourni, le script utilisera celui spécifié par défaut dans l'entrée PluginVersion de la variable de configuration $Config (définie au tout début du script lui-même).
• -t (ou -template) : Permet de spécifier l'emplacement du fichier template du plugin.xml
  • Si cette option est présente, le fichier spécifié doit exister et pouvoir être ouvert en lecture. Si ce n'est pas le cas, l'erreur est affichée et le script s'arrête.
  • Si cette option est absente, les répertoires et nom de fichier utilisés sont les entrées PluginTemplateDir et PluginTemplateName de $Config
  • Si le template n'est pas trouvé là, il est recherché dans le répertoire du script lui-même. Le nom de fichier utilisé alors est le PluginTemplateName de $Config
  • Si rien n'est trouvé, erreur et le script s'arrête.
  • Toute cette mécanique permet d'avoir plusieurs templates, selon les besoins, en plus de celui fourni par défaut, qu'il est donc inutile de modifier en général.
• <zip patchs> : Bien entendu, les fichiers patchs eux-mêmes (archives zip).
  • Il doit en exister au moins un (!!!)
  • Caractères "joker" autorisés, sous Linux comme sous Windows