7. Journal des mises à jour : Changelog

La documentation se gère comme le code source d'un logiciel. Les fichiers XML et les Makefiles représentent de code source du projet. Pour gérer les évolutions d'un volume important de code source dans le temps, il est essentiel d'utiliser un gestionnaire de contrôle de version.

De façon à ce que les (lecteurs|utilisateurs) des documentations du projet puissent suivre les évolutions «en temps réel», il est très utile de générer une page Web contenant le journal des mises à jour de l'ensemble du projet. Via un artifice de construction de ma page Web personnelle sur le site Linux France (AKA lfo), ce journal est placé dans le fichier README.html à l'adresse : ChangeLog [inetdoc.LINUX].

7.1. Génération de la page ChangeLog avec CVS

Depuis le début du projet [inetdoc.LINUX] en 2001 jusqu'en Novembre 2005, le gestionnaire de contrôle de version était CVS. Pour générer le journal au format XML, il est nécessaire d'utiliser un script fourni dans le paquet du même nom cvs2cl. Une fois le journal créé au format XML, on lui applique une feuille de styles XSL pour produire la page Web «lisible» au format XHTML.

Les règles de génération de la page Web contenues dans le Makefile sont :

# Date de départ de collecte Changelog.
# Construction du fichier README.html
START_LOG_DATE = 2005-01-01

<snipped/>

$(TARGET_DIR)/README.html:
        cvs2cl --prune --lines-modified --gmt --xml --xml-encoding utf-8 \
	 --noxmlns -f changes.xml -l -d '>$(START_LOG_DATE)'
        xsltproc -o $@ cl2html.xsl changes.xml
        rm -f changes.xml*

La feuille de styles XSL utilisée pour produire la page Web se présente comme suit :

<?xml version='1.0'?>
<xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform" version="1.0" >
  <xsl:output encoding="iso-8859-15" method="html" indent="yes"
    doctype-public="-//W3C//DTD HTML 4.01 Transitional//EN" />
  <xsl:template match="/changelog">
    <html>
    <head>
      <title>CVS-ChangeLog</title>
      <link rel="stylesheet" type="text/css" href="inetdoc.css" media="all" />
    </head>
      <body>
        <div id='container'>
        <h1 id='changelog'>Changelog - <xsl:value-of select="entry/date"/></h1>
          <xsl:for-each select="entry">
              <h4>
	      	<xsl:text>Fichiers édités par </xsl:text>
                <xsl:value-of select="concat(author, ': ', date, ' (', time, ')')" />
              </h4>
	      <pre>
	      	<xsl:value-of select="msg"/>
	      </pre>
              <ul>
                <xsl:for-each select="file">
		 <li>
                  <strong><xsl:value-of select="name"/></strong>
		  <br />
		  <span class="rev">
		  <xsl:text>Revision : </xsl:text>
		  <xsl:value-of select="revision"/>
		  <xsl:text>, status : </xsl:text>
		  <xsl:value-of select="cvsstate"/>
		  <xsl:text>, lignes ajoutées : +</xsl:text>
		  <xsl:value-of select="linesadded"/>
		  <xsl:text>, supprimées : -</xsl:text>
		  <xsl:value-of select="linesremoved"/>
		  </span>
		 </li>
                </xsl:for-each>
              </ul>
          </xsl:for-each>
	</div>
      </body>
    </html>
  </xsl:template>
</xsl:stylesheet>

7.2. Génération de la page ChangeLog avec SVN

Depuis Novembre 2005, le gestionnaire de contrôle de version des fichiers sources utilisé pour le projet [inetdoc.LINUX] est subversion (AKA SVN). Ce gestionnaire présente de nombreux avantages relativement au précédent (CVS). Il est possible de générer directement le journal des mises à jour au format XML sans avoir recours à un paquet supplémentaire. Il est cependant toujours nécessaire d'utiliser une feuille de styles XSL pour produire la page Web au format XHTML.

Depuis Avril 2007, le journal des mises à jour au format XML est modifié à l'aide d'un script perl de façon à ajouter les statistiques produites par la commande diffstat pour chaque fichier modifié. L'objectif de cette modification est de fournir une information sur l'importance des éditions sur les fichiers sources.

Les règles de génération de la page Web contenues dans le Makefile de génération et de publication du journal des éditions de fichiers source (Changelog) sont :

.PHONY: $(TARGET_DIR)/README.html
$(TARGET_DIR)/README.html: common/asvn2cl.xsl
     svn log --xml --verbose \
     -r{`date --date 'tomorrow' +%Y-%m-%d`}:{`date --date '9 months ago' +%Y-%m-%d`} \
     >changes.xml
     ./common/extract_changelog_diffstat.pl <changes.xml >changes.xml.new
     xsltproc -o $@ common/asvn2cl.xsl changes.xml.new
     rm -f changes.xml*

Le script Perl de modification du journal XML effectue les transformations de balises suivantes :

Résultat produit par la commande svn log --xml.

<paths>
  <path
    action="M">/trunk/prj/inetdoc/sources/sources.xml<path>
<paths>

Résultat après transformation par le script extract_changelog_diffstat.pl.

<objects>
<object>
<path
  action="M">/trunk/prj/inetdoc/sources/sources.xml<path>
  <stats>14 +++++++-------<stats>
  <object>
<objects>

Le script Perl extract_changelog_diffstat.pl de modification du journal est donné dans l'Annexe A, Script de transformation du journal XML de Subversion.

La feuille de styles XSL asvn2cl.xsl utilisée pour produire la page Web ChangeLog [inetdoc.LINUX] est donnée dans l'Annexe B, Feuille de styles XSL de génération du Changelog à partir du journal XML de Subversion.

Précédent		Suivant
6. Ajout d'un nouveau document	Sommaire	A. Script de transformation du journal XML de Subversion

[inetdoc.LINUX]