Créer des notes de version à partir d'une requête Jira

illustrations illustrations illustrations illustrations illustrations illustrations illustrations
#jira #flare #xslt #xml
post-thumb
                   

Publié le 5 mai 2022 par Andrew Owen (7 minutes)

Dans cet article, je vais décrire une solution pour simplifier le processus de création de notes de version dans MadCap Flare sur Windows à partir d’une requête Jira. Jira est une plateforme populaire de suivi des problèmes de Atlassian. Mais cette approche peut également être adaptée à toute autre plateforme qui peut exporter des problèmes au format XML et à tout outil de documentation basé sur XML.

Pré-requis

Nous allons exécuter un script à partir de la ligne de commande pour récupérer les informations dont nous avons besoin dans Jira, les traiter et produire un document Flare. Pour effectuer la récupération, nous utiliserons un outil appelé cURL (Client URL). Celui-ci devrait déjà être installé dans votre système d’exploitation, à moins que vous n’utilisiez une version de Windows antérieure à Windows 10.

Le traitement est effectué à l’aide d’un analyseur XSLT (eXtensible Stylesheet Language Transformations). Microsoft fournit MSXSL.EXE dans le cadre de Microsoft Core XML Services (MSXML) 6.0. Cependant, il ne prend en charge que XSLT 1.0. Je recommande donc d’utiliser Saxon, qui prend totalement en charge XSLT 3.0.

Vous aurez probablement besoin d’installer un processeur XSLT. Cela était autrefois compliqué, mais vous pouvez maintenant le faire avec node.js:

npm install -g saxon-js
npm install -g xslt3

Vous devriez probablement vérifier la politique informatique de votre entreprise avant de poursuivre. Vous devrez peut-être demander à votre service informatique d’installer le logiciel pour vous.

Saxon applique les instructions d’un fichier XSL pour transformer le XML brut récupéré par cURL en un document Flare avec le contenu requis.

Vous devrez créer une clé API Jira pour le script:

  1. Dans Jira, accédez à Your profile and settings > Manage account > Security et cliquez sur Create and manage API tokens.
  2. Cliquez sur Create API token.
  3. Entrez un Label, par exemple, Jira2Flare et cliquez sur Create.
  4. Cliquez sur Copy et collez le résultat dans un éditeur de texte.
  5. Cliquez sur Close.

Remarque: vous ne devez utiliser cette clé API que dans votre script. Le script doit être stocké dans un endroit où vous êtes le seul à pouvoir y accéder. Si vous pensez que votre sécurité a été compromise, dans Jira, naviguez vers Create and manage API tokens, localisez le token et cliquez sur Revoke pour le désactiver.

Vous aurez également besoin de la chaîne de requête Jira. L’explication des requêtes Jira dépasse le cadre de cet article, je vais donc supposer que vous avez déjà une requête de recherche qui renvoie les notes de mise à jour pour une version spécifique du logiciel:

  1. Ouvrez la requête dans votre navigateur et, dans le menu Actions (…), faites un clic droit sur Export XML et cliquez sur Copy link address (ou l’équivalent si vous n’utilisez pas Google Chrome).
  2. Collez le lien dans un éditeur de texte et remplacez tout signe de pourcentage simple (%) par un signe de pourcentage double (%%).
  3. Remplacez la chaîne fixversion par %fixversion% (avec des signes de pourcentage simples).
  4. Ajoutez un guillemet double (") au début et à la fin de la chaîne.

L’option Export XML formate la sortie sous forme de flux RSS. Cela détermine la structure du fichier XML, mais vous n’avez pas besoin de connaître quoi que ce soit sur les flux RSS pour les besoins de cet article.

Créer le script cURL

Dans l’exemple de script, je suppose que vous avez un champ Jira personnalisé avec le nom Release Notes. S’il s’appelle autrement, vous pouvez modifier le script en conséquence. S’il n’existe pas de champ équivalent pour vous indiquer quels tickets doivent être inclus dans une note de publication, vous devez demander à votre administrateur Jira d’en créer un.

En général, les versions dans Jira sont identifiées par une valeur fixversion. Nous pouvons créer un script Windows qui prend cette valeur en entrée et télécharge les résultats de la requête. Collez le texte suivant dans un éditeur de texte et enregistrez-le sous jira2flare.cmd:

    @echo off
    echo Please enter a fix version:
    set /p fixversion=""
    cls
    curl -o input.xml -u user@example.com:APIkey "Jira query with the % charcters escaped as %% and the fixversion entered as %fixversion%"
    Transform input.xml j2f.xsl > output.html

Remplacez user@example.com par votre adresse e-mail, APIkey par votre clé API, et remplacez la chaîne de requête Jira par celle de votre éditeur de texte.

La dernière ligne du script effectue la transformation. Nous y reviendrons dans un instant. Avant d’effectuer la transformation, vous devez vérifier que la commande cURL fonctionne. Si tous les paramètres sont corrects, un fichier appelé input.xml est créé.

Transformer la requête en un document Flare

Collez ce qui suit dans un éditeur de texte et sauvegardez-le sous j2f.xsl dans le même dossier que celui où vous avez sauvegardé jira2flare.cmd:

<?xml version="1.0" encoding="UTF-8"?>
<xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform" version="2.0">
  <xsl:output method="xml" version="1.0" encoding="UTF-8" indent="yes" />
  <xsl:strip-space elements="*" />
  <xsl:template match="/">
  <html xmlns:MadCap="http://www.madcapsoftware.com/Schemas/MadCap.xsd" MadCap:onlyLocalStylesheets="True">
    <head>
      <link rel="stylesheet" type="text/css" href="../Resources/Stylesheets/yourstyles.css" />
    </head>
    <body>
      <h1>Release Notes</h1>
      <table border="1">
        <tr>
          <th>Modules</th>
          <th>Summary</th>
          <th>Ticket</th>
          <th>Category</th>
          <th>Fix Versions</th>
          </tr>
          <xsl:for-each select="rss/channel/item/customfields/customfield">
            <xsl:if test="customfieldname[text()='Release Notes']">
              <tr>
                <td>
                  <xsl:value-of select="../customfield/customfieldname[text()='Modules']/../customfieldvalues/customfieldvalue" />
                </td>
                <td>
                  <xsl:value-of select="customfieldvalues/customfieldvalue" disable-output-escaping="yes" />
                </td>
                <td>
                  <xsl:value-of select="../../key" />
                </td>
                <td>
                  <xsl:value-of select="../customfield/customfieldname[text()='Category']/../customfieldvalues/customfieldvalue" />
                </td>
                <td>
                  <xsl:value-of select="../../fixVersion" />
                </td>
              </tr>
            </xsl:if>
          </xsl:for-each>
        </table>
      </body>
    </html>
  </xsl:template>
</xsl:stylesheet>

Le fichier XSL détermine quelles informations du fichier XML (la requête Jira) sont incluses dans le document Flare et comment elles sont formatées. Vous pouvez modifier cela en éditant le fichier XSL. Dans cet exemple, nous voulons les Modules, Summary, Ticket, Category et Fix Versions.

Voici un bref résumé de ce que ce fichier de transformation demande au processeur XSLT de faire:

  1. Transformer le fichier XML brut en fichier HTML en utilisant la feuille de style Madcap Flare.
  2. Créer un en-tête Release Notes.
  3. Créer un tableau avec les titres Modules, Résumé, Ticket, Catégorie, et Versions de correction.
  4. Pour chaque entrée du fichier XML source où le champ personnalisé Notes de parution existe, créez une ligne dans le tableau contenant les valeurs pertinentes.

Les valeurs des balises XSL du tableau sont des instructions au processeur XSLT sur la façon de naviguer dans le fichier XML source. Si vous souhaitez en savoir plus sur la transformation de XML à l’aide de XSLT, w3schools propose une introduction.

Maintenant, lorsque vous exécutez le script jira2flare.cmd, en plus du fichier input.xml vous devriez obtenir un fichier output.html que vous pouvez ouvrir directement dans Flare.

Résumé

Une chose importante à garder à l’esprit est que si vous éditez normalement vos notes de version dans Flare, avec ce processus vous devriez faire vos changements dans Jira. Ceci a le double avantage que les révisions peuvent être faites dans Jira, et que vos notes de version publiées correspondront à vos tickets.

Les transformations XSL sont un outil puissant pour convertir des documents XML d’une forme à une autre. En effet, nous avons à peine effleuré la surface de ce qui est possible. Si vous souhaitez aller plus loin, vous pouvez demander à votre équipe de développement d’automatiser le processus. Mais nous espérons que ce que vous avez appris ici vous aidera à accélérer votre flux de travail pour les notes de version.

Postface

Donc, automatisation. Voici un exemple d’action GitHub:

name: RSS to Flare
on:
  workflow_displatch
jobs:
  rss2flare:
    runs-on: ubuntu-latest
    permissions:
      contents: write
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: 20
      - shell: bash
        env:
          APIKEY: ${{ secrets.JIRA_API_KEY }}
          FIXVERSION: ${{ vars.FIXVERSION }}
        run: |
          curl -o input.xml -u user.name@example.com:$APIKEY "<jira query including $FIXVERSION>"          
      - name: install Saxon and transform XML
        run: |
          npm install -g saxon-js
          npm install -g xslt3
          xslt3 -s:input.xml -xsl:rss2falre.xsl -o:output.html          
      - name: check for changes
        id: changes
        run |
          git fetch origin main
          echo "result=$(git diff -quiet origin/${{ github.base_ref }} ${{ github.sha }} - ./ || echo 'changes-found')" > $GITHUB_OUTPUT
          continue-on-error: true
      - name: No changes found
        if: steps.changes.outputs.result != 'changes-found'
        run: echo "No changes found in the '$({ env.working-directory })' folder in comparison to the 'main' branch. Skipping commit."
      - name: Commit files
        if: steps.changes.outputs.result == 'changes-found"
        run: |
          git config --local user.email "github-actions@users.noreply-github.com"
          git config --local user.name "github-actions"
          git add
          git commit -a -m "Commit changes"          
      - name: Push changes
        if: steps.changes.outputs.result == 'changes-found'
        run: git push origin main

Image: Original par Danmeil Korpai.