Je commite en 9 leçons

… ou comment faire un bon commit

Cette page, explique aux développeurs comment faire un bon commit. Cependant, vu l'évolution très rapide de Metafor, cette page n'est pas toujours à jour.

Cependant, n'oublie pas, cher collègue, que tu peux aussi faire de ce monde un monde meilleur! Il te suffit de cliquer à droite de cette page sur le bouton “Edit this page” et tu peux immédiatement corriger une erreur! Merveilleux, n'est-il pas?

Je te souhaite donc un bon commit!

Commiter. Voilà un beau mot qu'il n'est pas facile d'utiliser en dehors du B52. Pourtant, en tant que développeurs de code, c'est une étape indispensable qu'il va falloir réaliser régulièrement (la notion de “régulièrement” étant très variable selon les personnes).

En effet, lorsque l'on est plusieurs à travailler sur le même code, il est indispensable d’utiliser un système de version. La version officielle de Metafor se trouve bien sagement dans le “repository”, et chaque développeur fait une copie de cette version sur son PC (“checkout”) pour pouvoir travailler dans son coin. Après avoir réalisé des développements, il arrive souvent un point où on souhaite réintégrer ceux-ci à la version officielle de Metafor (“commiter”), afin de sauvegarder son travail, d'avoir une nouvelle base de référence pour continuer à programmer, de permettre aux autres d'utiliser ses nouveaux développements…

Cependant, il ne suffit pas de brutalement aller modifier la version officielle! Avant de pouvoir commiter, il faut vérifier :

• que les nouveaux développements sont portables, en compilant sur différentes plateformes et compilateurs
• qu'il n'y a pas de régression dans les capacités de Metafor (c'est-à-dire que l'on est pas aller pourrir le travail des collègues), via l’exécution d'une batterie de tests sur différentes configurations.

Les différentes plateformes sur lesquelles la compilation doit être possible et la batterie lancée sont les suivantes :

Quand on essaie de réaliser cette procédure de commit, on oublie toujours une chose ou l'autre quand on n'a pas l'habitude. Voici donc une petite marche à suivre qui détaille, étape par étape, tout ce qu'il faut faire pour faire un beau commit pas foireux.

• On considère que les sources stations vont être dans /home/$USER/Metafor
• SVN est correctement configuré sur son PC
• Idéalement, il faut aussi savoir se connecter sur les stations sans mot de passe. Pour ce faire, suivez les instructions décrites ici. Ce n'est pas obligatoire, mais cela évite de taper son mot de passe deux cents fois par commit.
• Les programmes suivants (disponibles sur le NAS) doivent être installés sur son PC:
  • Samcef (normalement inclus dans les libs-vs2012)
  • Matlab
  • Scilab
  • GhostScript (dans les libs)
• Sous Windows, les chemins complets vers ces programmes doivent être définis à travers l'application “externalProgramPathGui.pyw” (présente dans “linuxBin”) ou être dans le PATH users de Windows.

Pour pouvoir commiter sa nouvelle version, il faut évidemment être à jour et posséder la version la plus récente de Metafor. A l'heure actuelle (juin 2016), Metafor est composé de 4 différents dossiers, qui fonctionnent avec deux systèmes de version différents.

Les dossiers oo_meta et oo_nda sont gérés par “SVN”. Pour mettre à jour, il suffit de sélectionner ces deux dossiers, clic droit, SVN Update.

Le dossiers parasolid et linuxbin sont gérés par “git” (voir le commit de Romain pour installer et comprendre git). Pour mettre à jour, on sélectionne le dossier, clic droit, TortoiseGit, Pull.

La fenêtre suivante s'ouvre. On laisse bien remote : origin, remote branch : master, et on clique sur OK.

Lors de la mise à jour des sources, des conflits peuvent évidemment arriver, si jamais les modifications réalisées ne sont pas compatibles avec celles introduites dans les derniers développements commités par les collègues. Dans ce cas-là il faut résoudre les conflits à la main. Plus on attend longtemps avant de commiter, plus le nombre de ces conflits augmente, donc il est intéressant de commiter régulièrement.

Une fois les sources mises à jour, il faut faire de même avec son projet Windows, d'abord en utilisant CMake, puis en compilant sous Visual Studio. Personnellement, je préfère toujours supprimer complètement mon projet et le recréer depuis le début (créer un dossier oo_metaB ou MetaBin, ouvrir fenêtre de commande, taper cmake -C ..\oo_meta\CMake\win64-vs2012.cmake ..\oo_meta, ouvrir le projet Visual Studio et complier), mais on peut (souvent mais pas toujours) aussi simplement utiliser CMake GUI, dans les libs de Luc:

On vérifie bien que la première ligne pointe vers oo_meta, la seconde vers oo_metaB, puis on clique d'abord sur Configure, et ensuite sur Generate. Il reste ensuite à recompiler son projet Visual Studio.

Une fois les sources à jour, l'idée est de les compiler et de lancer la batteries de tests sur les stations linux, spring et thorgal. Il faut donc déplacer les sources sur les stations en question.

Avant de déplacer les sources, deux petites opérations de nettoyage :

• Premièrement, dans oo_meta, on ouvre une fenêtre de commande et on tape python clean.pyw. Cela ouvre un petit utilitaire qui permet de nettoyer les crasses du projet. Cela n'est pas obligatoire, mais cela permet de supprimer les .pyc par exemple, ou des dossiers workspace qui traîneraient où il ne faut pas, pour éviter par la suite de commiter des fichiers qui ne doivent pas l'être. Attention qu'il ne faut pas aveuglément cliquer sur [Go] et tout supprimer, il me semble que cela supprime parfois des fichiers requis par certains cas-tests (à vérifier…)
• Deuxièmement, il est également bon de faire un “SVN Clean Up” de oo_meta et oo_nda, sans quoi les dossiers pourraient être trop gros pour être zippés correctement. Les options par défaut peuvent être laissées, attention de ne pas cocher “Delete unversioned files and folders”, “Delete ignored files and folders” et “Revert all changes recursively”.

Une fois le nettoyage réalisé, on peut zipper les sources avec WinRAR. Faire un fichier qui peut s'appeler, par example, MetaforDate.zip (attention, pas un fichier .rar) avec les quatre dossiers linuxbin, oo_meta, oo_nda et parasolid.

Ensuite, on transfère l'archive en question sur les stations en utilisant par exemple Filezilla. Pour se connecter aux stations :

• Hôte : spring.ltas.ulg.ac.be, thorgal.ltas.ulg.ac.be ou gaston.ltas.ulg.ac.be
• Compléter identifiant et mot de passe
• Port: 22
• Cliquer sur “connexion rapide”

Une fois connecté, il suffit alors de faire glisser l'archive zip dans un sous-dossier adapté, par exemple DateBaterry

Maintenant qu'on a déplacé les sources sur les stations, il reste à lancer les batteries dessus. Pour cela, il faut compiler les sources et lancer la batterie sous Linux64-gcc (thorgal), Linux64-icc (spring) et Linux64-clang (gaston).

On se connecte sur les stations grâce à PuTTY :

• Dans hôte, on tape spring.ltas.ulg.ac.be, thorgal.ltas.ulg.ac.be ou gaston.ltas.ulg.ac.be
• Dans port, 22
• On clique “Open”
• On tape son identifiant, puis son mot de passe
• On se positionne dans le bon dossier : cd DateBattery

Une fois connecté, on commence par taper la commande top pour vérifier que personne n'occupe la machine. Sur l'image ci-dessous, par exemple, 4 noeuds sont déjà occupés par Marco. Il est bien aussi de se renseigner pour voir si des collègues n'ont pas un commit super urgent prévu et ne pas leur voler la priorité. C'est donc l'occasion d'aller papoter un peu dans les bureaux.

Si personne n'est sur la machine, on lance alors le script comp.py.

Pour faire son choix dans le menu, il suffit de taper la lettre ou le chiffre précédant la commande en question dans le menu.

Parmi les lettres, seules les options 'b' et 'j' doivent être modifiées :

• b. Archive name. Chemin et nom des sources zippées de Metafor. Il faut donc taper b, puis écrire le chemin vers l'archive zip transférée précédemment (un simple TAB suffit si on est dans le bon dossier).
• j. Nombre de CPUs pour la compilation et la batterie (voir tableau ci-dessous pour le nombre de CPU des différentes machines). Mettre généralement à 4.

Les autres options, décrites ci-dessous, sont en général laissées par défaut :

• a. e-mail address. Adresse à laquelle les résultats de la batterie seront renvoyés.
• f. build options. Donner le nom du fichier de config CMake (voir tableau ci-dessous - le nom par défaut est généralement OK).
• g. debug mode. Laisser False
• h. nice value. Priorité de calcul pour la batterie: laisser 0 - priorité haute.
• k. Nombre de threads pour le calcul en parallèle.
• m. run Method. Laisser “batch”.
• q. is bacon present? Bacon est présent sur toutes les machines de batterie.

Concernant les chiffres :

• 1. Indique où sont les sources. Trois possibilités :
  • zip - les sources zippées et viennent d'être transférées par Filezilla. Attention, cela efface tout résultat de batterie précédent !
  • checkout - les sources doivent être obtenues par checkout depuis le repository. Attention, cela ne marche que si on peut se connecter aux stations sans mot de passe! Utile seulement pour compiler la version officielle de Metafor.
  • present - les sources sont présentes dans le même dossier. C'est ce qu'il faut cocher si Metafor a déjà été compilé et qu'on souhaite juste relancer quelques tests.

• 2. compile: True ou False. Attention, si True, cela efface tous les résultats de batteries précédents !

• 3. battery: True, False ou continue. Attention, True efface toute la batterie et la relance entièrement. continue ne relance que les tests qui n'ont pas tourné ou ne sont pas passés.

• 4. installer: False

Dans ce cas-ci, où on vient de transférer les sources par Filezilla, on veut avoir :

• 1 source - zip
• 2 compile - True
• 3 battery - True

Une fois qu'on est satisfaits avec les options, on appuie sur “G” et ça démarre! Pour info :

• G. Lancer le script en batch.
• S. Sauve la configuration courante.
• Q. Quitter le script

On répète ensuite l'opération avec la deuxième machine, thorgal; puis la troisième, gaston.

Une dizaine de minutes plus tard, on reçoit un mail qui indique si la compilation s'est bien passée ou non. Si non, il faut donc comprendre pourquoi. Si ça compile sous Windows mais pas sous Linux, l'erreur la plus fréquente est un problème de casse. Sous Windows, ce n'est pas grave de remplacer 'a' par 'A', mais sous Linux bien.

Si la compilation s'est bien passée, quelques heures plus tard, les fichiers de résultats de la batterie sont envoyés automatiquement par email. On recevra notamment un mail avec un fichier html reprenant les diffs sur la machine, qu'il faudra ensuite analyser.

Les batteries tournent déjà sur spring, thorgal et gaston, pour vérifier la portabilité sous Linux. Sous Windows, malheureusement, il n'y a pas de machine réservée, donc il faut faire tourner la batterie sur son propre PC. Pour ce faire:

Dans oo_metaB\bin\Release, on ouvre une invite de commande. D'abord, on tape python battery.py clean pour effacer les résultats de batteries antérieures.

Toujours dans la fenêtre de commande, on tape à présent python battery.py -j 4 -l run. Cela lance la batterie de tests sur 4 processeurs (-j 4), en priorité faible (-l, pour continuer à pouvoir utiliser l'ordinateur en même temps).

Une fois la batterie finie, toujours dans l'invite de commande, on tape python battery.py verif puis python battery.py diff. Cela génère, dans le dossier oo_metaB\bin\Release\verif, un fichier Windows-diffs.html qui contient toutes les différences entre les résultats des tests lancés ici et ceux de la version officielle. Le fichier ressemble à l'image ci-dessous :

A présent, on a donc lancé les batteries sur thorgal, spring, gaston et son PC. On a donc reçu 3 fichiers diffs par email, et le troisième se trouve dans oo_metaB\bin\Release\verif. Il faut maintenant comprendre ces fichiers pour décider si on peut commiter ou non.

Première chose à regarder : les “FAILED”. C'est assez simple, tant que au moins un des trois fichiers de diff commence par la section 'FAILED' on ne commite pas! Cela veut dire que certains tests n'ont pas réussi à tourner jusqu'au bout (d'où le nom de failed). Il faut donc comprendre pourquoi, modifier son code et/ou ses tests, et relancer les tests.

Deuxième chose à regarder, le rouge! Un résultat est affiché en rouge si la donnée que l'on est censé observé est manquante. Il y a deux cas possibles :

• Si on a ajouté un nouveau test, il n'était pas dans la batterie précédemment. Par conséquent, la donnée manquante (missing!) se trouve dans la colonne old (voir ci-dessus, test filageExtrusion). C'est un cas tout à fait normal.
• Par contre, si le missing! se trouve dans la colonne new, c'est plus embêtant, cela veut dire qu'une grandeur qui était obtenue précédemment, dans la version officielle, ne l'est plus! Plusieurs possibilités :
  • Soit le test correspondant est également dans la section des failed. Facile à comprendre, le test n'a pas pu tourner jusqu'au bout, donc n'a pas pu écrire les résultats, ce qui explique le missing!. Il faut comprendre pourquoi et refaire tourner le test (voir ci-dessus, test backwardExtrusion3DRemeshing).
  • Soit le test correspondant n'est pas dans les failed, mais l'utilisateur a volontairement modifié les données qui sont écrites. Dans ce cas-là tout va bien.
  • Enfin, le test n'est toujours pas dans les failed, mais l'utilisateur n'a normalement rien modifié. C'est une situation anormale, il faut investiguer.

Troisième chose à regarder, les diffs proprement dites. Une fois qu'on n'a plus de tests dans les failed, et qu'on a compris tout ce qui est en rouge, on regarde les valeurs. C'est ici que c'est difficile, et que ça demande de l'expérience pour vraiment comprendre, car beaucoup de tests changent légèrement selon les machines. La machine spring est normalement la plus stable; je conseille donc de d'abord regarder les changements sur cette machine-là.

Quelques conseils:

• La première série, “STP”, affiche le nombre de steps d'une simulation. Cela peut changer d'un cas à l'autre, mais normalement pas beaucoup. Regarder donc que la variation relative ne soit pas trop élévée.
• Deuxième série, “ITE”, nombre d'itérations mécaniques d'une simulation. Même remarque que pour les steps.
• Troisième, “INW”, Energie interne. Il faut également vérifier que les valeurs de changent pas trop, mais comme l'énergie est parfois très, très faible, les variations relatives sont parfois très élevées. Regarder donc aussi les valeurs absolues.
• Quatre, “EXT”, valeurs diverses que les collègues ont décidés de vouloir vérifier en lançant les batteries. Pareil, vérifier que les variations sont faibles.
• Cinq, “EXW”, énergie externe, idem énergie interne.
• Six, “LKS”, fuite de mémoire. Certains tests varient parfois un peu, mais il est très important de vérifier que l'on a pas une augmentation sensible des tests, cela veut dire qu'on a ajouté des leaks dans le code. Lorsqu'on ajoute des nouveaux tests, il faut vérifier que la valeur est bien 0.
• Sept, “CPU”, vérifier qu'on a pas une forte augmentation de tous les cas tests sur les stations.
• Huit, “MEM”, mémoire, idem CPU.

Il faut noter qu'il y a des tests qui sont connus pour être instables. Il est assez fréquent que, les tests “mtFrequencyAnalysis”, “mtSuperElement”, “apps.XFEM” et d'autres présentes des diffs sans raison apparente. Petit conseil pour distinguer les “vrais diffs” des autres, lancer deux séries de batteries, une avec la version officielle de Metafor à laquelle on ne touche pas, une avec la version de développement. Ça permet de détecter les diffs à prendre en compte et celles qui ne sont pas graves (si pas de diff entre les diffs de Offi et Dev, on peut commiter)

Très souvent, on n'est pas prêt à commiter du premier coup. Que faire donc si la batterie n'est pas bonne? Cela dépend de si le code source de Metafor a dû être modifié. Si oui, alors on doit relancer toutes les batteries. Oui, toutes ! On recommence donc à l'étape deux, à savoir transférer les sources sur les stations, et on relance les batteries dessus et sur son PC.

Si par contre les erreurs proviennent des tests eux-mêmes (donc que l'on a modifié les tests mais pas le code source), il suffit alors de relancer juste les tests en question.

Sur les stations. Plusieurs façons de faire, j'en présente une qui me semble la plus simple:

• Transférer via Filezilla les différents tests qui ont été modifiés.
• Toujours via Filezilla, se rendre dans oo_metaB/bin et supprimer les fichiers .res des tests en question.
• Via Putty, dans le dossier où se trouvent les sources (DateBattery si vous faites comme moi), lancer comp.py avec les commandes suivantes :
  • 1 source : present (elles sont déjà ici vu qu'on a déjà compilé et lancé une batterie précédemment)
  • 2 compile : false (sinon on efface tout Metafor et les résultats de batterie)
  • 3 battery : continue (ne relance que les tests qui n'ont pas de .res)

Une fois que les quelques tests ont tourné, on reçoit par email un nouveau fichier diff que l'on peut analyser.

Sur le PC. On suit la même logique, une fois les tests modifiés, on supprime les .res correspondants dans oo_metaB/bin/Release, puis on ouvre une fenêtre de commande dans ce même dossier et on tape simplement python battery.py -j 4 -l run. Seuls les tests qui n'ont pas de .res seront relancés. On retape ensuite python battery.py verif et python battery.py diff et on a un nouveau fichier de diff dans le dossier verif.

Cette étape est à répéter jusqu'à ce que les trois fichiers de diff soient bons. Pour les nouveaux, c'est bien de demander confirmation à ce stade, pour pas mettre certaines personnes de mauvaise humeur après. Une fois qu'on est bon, on arrive enfin au commit proprement dit.

Le moment tant attendu arrive enfin: on commite !

D'abord, on parcourt l'ensemble des fichiers modifiés pour écrire proprement sa page de commit. Cette page a pour but de garder des traces des changements et d'expliquer aux collègues le travail réalisé. Il faut donc qu'elle soit suffisamment détaillée pour donner une idée précise de ce qui a été fait.

Ensuite, on clique droit successivement sur oo_meta, oo_nda, puis on va sur “Tortoise SVN” et sur “Check for modifications”. Dans la fenêtre qui s'ouvre, on coche “show unversioned files” et “show ignored files”.

Concernant les “non-unversioned” (c'est à dire les nouveaux fichiers que l'on a créé), on rajoute ceux qu'il faut ajouter. Cela se fait par clique droit sur les fichiers, tortoise svn add, sans oublier d'indiquer \$Id\$ au début de chaque fichier.

Ensuite, on clique droit sur oo_meta, oo_nda (seulement ceux où des modifications doivent être commitées) et on clique sur “SVN commit”. On prend note des fichiers ajoutés, supprimés et déplacés avant de fermer la fenêtre SVN pour vérifier que se page de commit est bien complète

On se connecte avec PuTTy et on tape :

cd /home/$USER/Metafor/oo_meta/apps/verif
svn commit *Linux64-icc.txt

L'éditeur de texte vi vi Tutorial se lance dans l'invite de commande. Si on ne désire pas ajouter de commentaires supplémentaires dans le fichier texte ouvert, on tape

:wq

c'est-à-dire “write” et “quit”.

Ensuite, il suffit de choisir l'option “continue”, c'est-à-dire taper “c”, et d'insérer son mot de passe “svn” pour effectuer le commit.

Log message unchanged or not specified
(a)bort, (c)ontinue, (e)dit : 

c
Password:
Sending    CPU-Linux64-icc.txt
Sending    EXT-Linux64-icc.txt 
Sending    EXW-Linux64-icc.txt
Sending    INW-Linux64-icc.txt
Sending    ITE-Linux64-icc.txt
Sending    LKS-Linux64-icc.txt
Sending    MEM-Linux64-icc.txt 
Sending    STP-Linux64-icc.txt
Transmitting file data ........
Committed revision 1677.

Faire la même chose sur thorgal (*Linux64-gcc.txt) et gaston (*Linux64-clang.txt).

A présent, le commit est supposé terminé, les étapes suivantes sont de la vérification.

• Sur PC : refaire un checkout des sources, puis recompiler le projet (ou mettre à jour sa version officielle et la recompiler). Puis on lance par exemple apps.qs.cont2 pour voir si tout va bien.
• Sur les stations, on fait un checkout des sources et on recompile les sources avec comp.py avec les options suivantes :
  • 1 source - checkout
  • 2 compile - True
  • 3 battery - False

Une fois que le commit est terminé et qu'on a vérifié que tout fonctionne bien comme on le voulait, il est temps d'envoyer un petit mail au groupe Google du service, avec le lien vers sa page de commit et des commentaires éventuels.

Si par contre on se rend compte qu'on a fait une boulette, on prend son courage à deux mains, on fait ses adieux à ses proches, on met son armure et on va trouver Luc…

En théorie, il faut ensuite mettre à jour l'image d'évolution du temps CPU de la batterie sur le site (obligatoire si on a ajouté des nouveaux cas-tests). Bon, j'avoue que ça j'ai jamais fait… Pour le faire, on va dans oo_meta et :

• Si on n'a pas matplotlib:

  python stats.py -plot sum apps/verif/CPU-Linux64.txt

• Si on a matplotlib:

  python stats.py -matplot sum apps/verif/CPU-Linux64.txt

• Copier l'image et la mettre sur le site en remplacement de l'ancienne

Amener de la tarte ou du gâteau pour fêter son commit réussi. Malheureusement, il s'agit d'une tradition qui se perd, on ne mange plus du gâteau que pour les anniversaires. C'est bien triste, surtout quand on voit comme ils étaient heureux à l'époque: