Les revues de codes avec Crucible

crucible_blue

La revue de codes fait partie des bonnes pratiques du développement logiciel. Même si certains la voient comme du flicage ou estiment qu'elle prend trop de temps, la pratique de la revue de codes par un tiers permet d'avoir un œil extérieur, pour éventuellement déceler des incohérences sur un développement. La revue de codes doit être vu comme un gage supplémentaire de la qualité d'un livrable au même titre que la mise en place de tests.

Un moyen classique de faire de la revue de codes : 2 développeurs, celui qui a fait le développement et un relecteur, qui prennent du temps ensemble pour faire la revue de codes sur un poste pour échanger sur ce qui a été fait. L'avantage de cette méthode est d'avoir les échanges en direct avec l'auteur du code. Les inconvénients, il faut que l'auteur et le relecteur soient disponibles en même temps, ce qui n'est pas toujours évident, mais également il n'y a pas de trace du temps passé pour la revue, ni des échanges si d'aventure les éventuelles corrections suite à la revue doivent être effectuées par une troisième personne, le fameux "truck factor".

Présentation

Des outils existent  pour justement améliorer le processus de revue de codes et notamment Crucible.

Crucible un produit, payant, distribué par Altasian permettant de créer, planifier et suivre les revues de codes. Il se connecte à un dépôt de fichiers versionnés, exemple git, pour permettre de sélectionner le code devant être soumis à la revue de codes soit par nom de commit, de branche, ou en sélectionnant des fichiers précisément. Tous les membres d'une équipe peuvent consulter les revues de codes passées et en cours, échanger dessus, créer des rapports sur les revues de codes.

Installation

Vous pouvez télécharger une version d'évaluation de Crucible sur le site d'Altasian. Ensuite il suffit de suivre la procédure d'installation suivant l'OS sur lequel vous êtes dans la documentation en ligne.

En pré-requis, vous aurez besoin d'avoir :

  • une jvm 8 minimum pour les versions 4 de Crucible, et la variable JAVA_HOME de configurée
  • Git

Configuration

Une fois Crucible installé, nous allons configurer notre instance pour permettre la création de revues de codes. Dans un navigateur Web, tapez l'url suivante "http://localhost:8060" (ou celle que vous avez configuré au moment de l'installation de Crucible)

Tout en bas de la page vous trouverez un lien "Administration" à côté du numéro de version de Crucible

admin_link

Quand vous cliquez dessus, vous devez saisir le mot de passe administrateur que vous avez renseigné pendant la phase d'installation. Vous accédez ensuite à l'interface d'administration de votre instance Crucible, via laquelle vous allez configurer votre dépôt de fichiers, votre projet et la liste des utilisateurs.

Ajouter un dépôt de fichiers

Dans le menu de gauche vous avez un lien "Repositories" qui permet d'ajouter un nouveau dépôt de fichiers en cliquant sur le bouton "Add repository". Une pop-up s'ouvre et vous propose de sélectionner le type de dépôt, Git par exemple, de lui donner un nom et éventuellement une description. Les étapes qui suivent permettent notamment de renseigner l'adresse du dépôt.

repo

 

Créer un projet

Toujours dans l'interface d’administration il nous faut créer un projet pour associer nos revues de codes futures. En cliquant sur le lien "Projects" dans le menu de gauche vous arriverez sur l'écran de gestion des projets.

projects

Vous verrez qu'il y a un projet par défaut qui se nomme "CR", le bouton "Add new project"  ouvrira une nouvelle pop-up dans laquelle vous saisirez les informations de votre nouveau projet avec en particulier la sélection de votre dépôt de fichiers.

Ajouter des utilisateurs

Dernière étape l'ajout d'utilisateurs. Toujours dans l'administration vous avez une rubrique "User settings" avec plusieurs liens possibles, tout dépend du choix du mode d'authentification de vos utilisateurs, qui peut se faire via un annuaire LDAP par exemple. Pour une utilisation simple vous pouvez cliquer directement sur le lien "Users" où vous pourrez ajouter de nouveaux utilisateurs avec des identifiants directement stockés au niveau de Crucible.

users

Pour plus de détails sur les différentes possibilités de configuration je vous invite à consulter la documentation en ligne.

Exemple de revue de codes

Maintenant que notre projet Crucible est configuré nous allons pouvoir dérouler un exemple de revue de codes. Crucible permet plusieurs worflows de revue de codes, nous allons faire le plus simple et peut-être aussi le plus répandu, à savoir un auteur et un relecteur.

Créer la revue de codes

Il faut vous connecter avec un des utilisateurs créés précédemment puis cliquer sur le bouton "Create review".

bt_create_review.

Une pop-up d'édition s'ouvrira pour la sélection du projet lié à votre revue.

select_project

Quand vous aurez cliqué sur "Create review", vous pourrez sélectionner le contenu de votre revue.

select_content_review1

On va sélectionner "Browse changesets" pour accéder à la liste des commits et sélectionner un commit qui sera l'objet de la revue. Vous pouvez tout à fait sélectionner plusieurs commits suivant les besoins.

select_commit_review1

Une fois le commit sélectionné vous pouvez désigner le relecteur en cliquant sur le bouton "Edit Details".

select_reviewer

Ici nous ne sélectionnons qu'un seul relecteur, parmi la liste des utilisateurs que nous avons créée précédemment, mais vous pouvez sélectionner plusieurs relecteurs ou des groupes de relecteurs, mais ce n'est plus le même workflow de validation.

Une fois votre relecteur sélectionné vous pouvez cliquer sur "Done", votre revue passera au mode "Ready" ou "Start review" et là votre temps passé sur la revue sera comptabilisé. On va cliquer sur "Done" car nous avons créé la revue et c'est plutôt le relecteur quand il débutera vraiment sur la revue de codes qui démarrera la revue.

Démarrer la revue de codes

En vous connectant avec le compte de l'utilisateur "relecteur" vous pourrez accéder à la liste des revues de codes en attentes de traitement, sélectionner la revue à traiter et cliquer sur "start review".

Le relecteur peut alors commencer sa revue, il arrive sur le détail de cette dernière.

detail_review

Il peut voir les fichiers ciblés, ainsi que les objectifs si ces derniers ont été renseignés. Un chrono en haut dans la barre d'outil au même niveau que le bouton de filtre comptabilise le temps passé sur la revue. En cliquant sur un fichier le relecteur affiche les modifications faites par le développeur par rapport au commit d'origine.

Quand le relecteur constate quelque chose dans un fichier il peut ajouter un commentaire sur la ligne en question. Il peut soit cliquer sur "Keep draft", dans ce cas son commentaire est gardé en mode brouillon et non visible par les autres utilisateurs ; soit cliquer sur "Comment", son commentaire sera alors directement visible sur la revue par toutes les personnes qui peuvent y accéder.

review_add_comment

Une fois que le relecteur estime avoir terminé, il clique sur le bouton "Complete" en haut à gauche.

complete_button

Si au moment de terminer la relecture, certains fichiers n'ont pas été revus, Crucible signale que des fichiers n'ont pas été lus.

unreviewed_files

De même si des commentaires sont restés à l'état "draft" Crucible alerte le relecteur.

drafts_comment

Une fois que le relecteur estime avoir terminé il pourra cliquer sur "Complete", ce qui signifie que l'auteur de la revue peut soit reprendre son développement si la relecture a révélé des points nécessitants des correctifs, soit passer sa tâche de développement à "terminée".

Prendre en compte la revue de codes

L'auteur de la revue peut consulter à tout moment les commentaires déposés par les relecteurs et lui même commenter les commentaires.

Voilà une revue avec les éléments commentés:

fichier_avec_nb_comment

A côté de chaque fichier on peut voir s'il y a eu des commentaires de laissés et combien par fichier. En cliquant sur un fichier on accède au détail:

mark_as_read

L'auteur peut alors indiquer qu'il a lu le commentaire en cliquant sur "Mark as read".

réponse

Ou ajouter un commentaire en cliquant sur "Comment".

Une fois que l'auteur à terminé de prendre en compte tous les commentaires qui en ont été faits, il peut décider de clôturer la revue en cliquant sur le bouton "Close".

close

Ce qui met fin au workflow de la revue.

Conclusion

L'exemple déroulé précédemment est plutôt simple mais il permet de constater que Crucible est assez rapide à mettre en place, simple d'utilisation et offre une solution de relecture complète et fonctionnelle. Crucible offre d'autres outils comme des notifications à destination des relecteurs pour leur signaler qu'ils ont des revues de codes en attente, des fonctionnalités de partages des résultats des  revues, des possibilités d'éditions de rapports.

Une dernière chose qui est très intéressante avec Crucible c'est son intégration avec Jira. Il est tout à fait possible de faire communiquer les deux outils, ce qui permet d'intégrer totalement le processus de revue de codes dans l'évolution du développement d'une tâche. Le contexte de la tâche peut être copié dans les objectifs de la revue de codes, et le résultat de la revue de codes sera directement visible dans le contenu de votre tâche, dans votre board Jira, et donc accessible par tous les membres du projet.

Laisser un commentaire

Votre adresse de messagerie ne sera pas publiée. Les champs obligatoires sont indiqués avec *

Captcha *