jeudi 26 septembre 2013

Suivre le développement des règles métier avec Dolphin et Jenkins

Update : une démo de la page statique est disponible à cette adresse : http://dolphindemo.flo.cloudbees.net/

Dolphin est un plugin Maven d'analyse d'annotations de suivi des exigences métier dans le code Java. Il permet d'assurer la traçabilité de règles métier depus les spécifications détaillées et le code. Il permet de connaitre quelle méthode implémente une règle métier particulière et le niveau d'avancement de celle-ci.

C'est un outil que j'ai développé afin d'assurer la traçabilité et avoir une idée de l'avancement de l'implémentation des règles métier au sein des projets.

Nous allons voir comment le mettre en place sur un projet, puis comment tirer parti de son usine logicielle et de Jenkins pour récupérer les indicateurs de manière automatisée en "quasi" temps réel.
Les sources de Dolphin sont récupérable à cette adresse : https://github.com/florentdupont/dolphin.

Enrichir le code avec l'API

 l'API comporte deux annotations :
  • @BusinessRule, pour la traçabilité des règles métier
  • @DevelopmentStatus, pour le suivi d'avancement.
L'annotation @BusinessRule indique les règles métiers implémentées sur une méthode. Cette annotation porte 2 attributs : 
  • id représente l'identifiant de la règle 
  • version représente la version de la règle. 
Par exemple :
  @BusinessRule(id="RG_0009", version="0.1")
  public void myMethod() {
      // blabla
  }

Si plusieurs règles sont appliquées sur une méthode, alors on peut indiquer les différents identifiants en spécifiant les valeurs multiples entre accolades {} : Dans l'exemple ci dessous, myMethod() implémente la règle RG_0009 en version 0.1 et la règle RG_0010 en version 0.2.
  @BusinessRule(id={"RG_0009", "RG_0010"}, version={"0.1", "0.2"})
  public void myMethod() {
    // ...
  }
L'annotation @DevelopmentStatus permet d'indiquer l'avancement d'un développement. L'annotation porte sur une méthode. Par exemple, une méthode en cours de développement :
  @DevelopmentStatus(StatusType.ONGOING)
  public void myMethod() {
    //...    
  }
Il existe 5 types de statut :

  •  TODO : méthode à implémenter 
  • ONGOING : méthode en cours de développement 
  • DONE : méthode implémentée, mais pas encore testée 
  • TESTED : méthode testée unitairement. Passe les tests unitaires 
  • INTEGRATED : méthode testée en intégration. Passe les tests d'intégration. 
Bien que les deux annotations pourraient être utilisées indépendamment, l'intérêt est évidemment de les utiliser conjointement afin de pouvoir bénéficier de l'avancement de l'implémentation des règles métier. L'exemple ci-dessous montre un exemple d'utilisation conjointe.
  public class MyClass {

    @BusinessRule(id="RG_0001", version="1.0")
    public void myMethod1() {
      // ...
    }

    @BusinessRule(id="RG_0016", version="1.0")
    @DevelopmentStatus(StatusType.DONE)
    public void myMethod2() {
      // ...
    }
}

Analyser les résultats

L'outil fait une analyse statique sur le code compilés (*.class). J'ai implémenté cette analyse en utilisant la librarie ASM qui permet de faire de l'analyse de Bytecode Java. L'utilisation d'une analyse statique depuis le Bytecode est plus complexe à mettre en oeuvre que de l'introspection (quoique...) mais elle présente surtout l'intérêt de pouvoir faire une analyse sans avoir à charger dynamiquement une classe. La classe peut donc très bien ne pas avoir ses classes liées chargées pour être analysée (ce qui est très utile lors de très gros projet et de Maven Dependency Hell...).

Une façon très simple de lancer l'outil, une fois installé, est de lancer la commande suivante : 

  mvn clean package -DskipTests com.dolphin:dolphin-maven-plugin:1.3:dolphin -DdolphinPrefix=com.mypackage.test
Le résultat de l'analyse est disponible dans le répertoire target/dolphin sous la forme d'un rapport HTML.

Le rapport HTML est une application HTML5 statique qui permet d'afficher une échelle du nombre de méthode analysées, ainsi que le status d'avancement de chaque méthode. Le tableau récapitulatif peut être trié par classe, par méthode, par règle ou par version. Il propose également une zone de recherche.
L'export XLS est également possible.

Intégration dans Jenkins 

L'intérêt est de pouvoir automatiser cette analyse et de l'intégrer dans Jenkins pour pouvoir disposer, de manière régulière et en quasi-temps réel, l'avancement.

Etant donné que Dolphin est disponible sous la forme d'un plugin Maven, il est tout à fait possible de l'intégrer à une construction Jenkins.

Voici un type de paramétrage pouvant être mis en place : 
Ce qui déclenche le Build : 
Scrutation de l'outil de gestion de version : H/20 * * * 1-5 
Build : 
Goals et options : 
  mvn clean package -DskipTests com.dolphin:dolphin-maven-plugin:1.3:dolphin -DdolphinPrefix=com.mypackage.test
Action à la suite de Build :
Archiver des artefacts : fichiers à archiver :
target/dolphin/**

C'est cette dernière étape qui va nous intéresser. Nous utilisons Jenkins comme "serveur Web", en mettant à disposition les fichiers HTML statiques directement accessible depuis ses constructions.
En cliquant sur index.html, on se rend compte que le résultat est accessible sur une URL du type :
http://MY_SERVER/jenkins/job/MY_JOB/BUILD_NUMBER/artifact/target/dolphin/index.html
On peut donc facilement, en gérant la rétention des constructions, garder une version de l'export par construction et ainsi garder un historique des différentes analyses Dolphin.

 L'intérêt pour le chef de projet est d'avoir une vision de la dernière analyse. Dans ce cas, on tire parti des URL Jenkins pour nous aider puisque Jenkins met à disposition les dernière construction sous un formalisme d'URL toujours identique, à savoir :;
http://MY_SERVER/jenkins/job/MY_JOB/lastSuccessfulBuild/artifact/target/dolphin/index.html
Ce lien peut ensuite être utilisé pour accéder rapidement aux résultats de dernière analyse, peu importe le numéro de construction utilisé par Jenkins, et notamment être utilisé directement depuis un tableau de bord par exemple.

samedi 21 septembre 2013

Jenkins & SVN : Afficher la révision comme numéro de build

Le numéro de build indiqué par défaut lors de la construction dans Jenkins est un numéro qui s'incrémente à chaque construction. Ce numéro - mis à part de nous indiquer à combien de construction nous sommes rendu - n'apporte pas plus d'information.


Ce qui serait utile, par contre, c'est de savoir rapidement à quelle version de source cette construction correspond afin de disposer d'une meilleure traçabilité entre Source SVN -> artefact Jenkins.
Aucun plugin ne permet de le faire actuellement, nous allons voir comment on peut cependant le mettre en place rapidement.

Retour sur les versions de SVN

Dans notre contexte, nous avons plusieurs projets disponibles sur un repository SVN. Chaque projet est donc sur un sous-répertoire depuis la racine du dépot. A chaque commit (peu importe sur quel projet), le numéro de révision du dépôt est incrémenté.
Ce numéro de révision est global : il permet de restituer l'état d'un repository à un révision donnée.
Pour chaque sous répertoire, nous disposons d'un second indicateur : Last Changed Revision qui indique le dernier numéro de révision qui à modifié le répertoire en cours

Nous pouvons récupérer ces informations depuis la ligne de commande en se positionnant sur un répertoire de source précédemment checkoutée :

$ svn info
Path: .
Working Copy Root Path: D:\projets\toto\source\
URL: http:/xxx/usvn/svn/toto/trunk
Repository Root: http://xxx/usvn/svn/toto
Repository UUID: a1ebbc07-6c76-4030-a489-aa0d2fd72fa2
Revision: 11372
Node Kind: directory
Schedule: normal
Last Changed Author: fdupont
Last Changed Rev: 11360
Last Changed Date: 2013-09-11 17:23:54 +0200 (mer., 11 sept. 2013)

Les informations qui nous intéressent apparaissent dans les champs "Revision" et "Last Changed Rev".

Prise en compte dans Jenkins

Pour la prise en compte dans Jenkins, il faudra ajouter le plugin Hudson Groovy builder

Dans la configuration du build, ajouter une Pre steps avec execution de script Groovy "System". Exécuter en tant que script "System" signifie que le script sera exécuté dans la même JVM que Jenkins, ce qui permet d'avoir la main sur les objets Jenkins. C'est ce qui va nous permettre de modifier le nom du build ainsi que sa description.

Les deux lignes suivantes sont les imports des packages jenkins.
  import hudson.model.*
  import hudson.util.*
Récupère l'instance du build courant
  def build = Thread.currentThread().executable
On récupère ensuite le workspace du build courant, c'est à dire le répertoire dans lequel les sources sont chéckoutée. Ce répertoire contient le répertoire .svn qui sera utilisé par la commande svn info.
  def workspace = build.getWorkspace()
En groovy, le moyen le plus simple d'exécuter une commande shell et de récupérer le résultat est de passer par une tâche Ant.
  def ant = new AntBuilder()

  ant.exec(executable: "svn", outputproperty: "output", dir: workspace){
    arg(line: "info")

  }
La sortie est récupérée depuis la variable "outputProperty" puis sert à alimenter la variable svnInfo.
  svnInfo = ant.project.getProperty("output")
On utilise ensuite des expression régulière pour récupérer le numéro de révision ainsi que le LCR (Last Changed Revision.
  def pattern = /Last\s+Changed\s+Rev:\s+(\d+)/
  def matcher = (svnInfo =~ pattern)
  def lcr = "Last changed revivion : <b>" + matcher[0][1] + "</b>"
  
  pattern = /Revision:\s+(\d+)/
  matcher = (svnInfo =~ pattern)
  def rev = "r" + matcher[0][1]
Le nom du build est ensuite modifié avec l'intitulé de la révision et la description est renseignée avec le LCR.
  build.setDisplayName(rev)
  build.setDescription(lcr)

Au complet, ça nous donne :
  import hudson.model.* 
  import hudson.util.*

  def build = Thread.currentThread().executable
  def workspace = build.getWorkspace()
  def ant = new AntBuilder() 

  ant.exec(executable: "svn", outputproperty: "output", dir: workspace){ 
    arg(line: "info") 
  }

  svnInfo = ant.project.getProperty("output")
  def pattern = /Last\s+Changed\s+Rev:\s+(\d+)/ 
  def matcher = (svnInfo =~ pattern)
  def lcr = "Last changed revivion : " + matcher[0][1] + ""

  pattern = /Revision:\s+(\d+)/ 
  matcher = (svnInfo =~ pattern)
  def rev = "r" + matcher[0][1]

  build.setDisplayName(rev)
  build.setDescription(lcr)


Lors de la prochaine construction, depuis la View, on verra bien apparaitre notre numéro de révision


Dans la vue Constructions, le LCR apparait en tant que description :




Note complémentaire : pour les ceux qui utilisent SVN depuis Windows, l'outil en ligne de commande est internationalisé et répondra donc en français. Pour restituer les sorties consoles en anglais, ajouter la variable d'environnement suivante :
  set LC_MESSAGES=en_US
L'article original : http://jayflowers.com/WordPress/?p=258