Github et les tickets

Création ticket

• De préférence, rédiger les tickets en anglais.
• Être le plus précis possible sur le problème rencontré, et notament sur comment le reproduire.
• Laisser les membres du projet (sur GitHub) attribuer les labels, milestones et assignations qu'il convient.

Travailler à plusieurs

• Projet libre et open-source. C'est donc aux développeurs de s'assigner eux-même les tickets sur lesquels ils souhaitent travailler.
• On évite de travailler à plusieurs sur un même ticket afin de limiter les problèmes lors des commits.
• Chaque développeur doit se créer sa propre branche (avec pour nom par exemple "MonPseudo-dev") pour travailler. Il pourra ensuite merger avec la branche principale quand il aura terminé.
• Chaque commit doit avoir un commentaire en anglais (et de préférence utile...).

Les branches

• La branche master correspond toujours à la dernière version utilisable du serveur.
• Quand une version stable est officialisée, on la tag avec son numéro de version officiel.
• Les développeurs doivent travailler sur leur propre branche et merger avec master seulement quand ils ont terminé.

Milestones

• Attention, les milestones sont les échéance officielles de Regovar, merci de laisser Oodnadatta ou Ikit s'en occuper.
• La prochaine milestone et sa progression sont visibles par tout le monde directement via le client officiel QRegovar.

Documentation

• Il est important de bien documenter le code. Chaque fonction et chaque classe doit avoir un commentaire en-tête (python : entre triple """) (C++ avec commentaire //! ou /*! */).
• Penser aussi à mettre à jour la documentation en ligne une fois que vous avez terminé ce que vous avez commencé. Merci de faire attention à respecter l'organisation et la mise en forme utilisé pour ReadTheDoc.
• Ne pas hésiter à mettre un ticket GitHub pour ne pas oublier de faire la traduction dans les autres langues si vous ne le faites pas.
• Si vous créez de nouvelles erreurs, se référer à la documentation (ci-dessous) pour y associer un code et intégrer correctement ces erreurs dans le système mis en place.

Traduction

Tout le code et les messages du serveur doivent être rédigés en anglais. La traduction se fait uniquement côté client grâce notament aux outils proposés par le framework Qt.

Tests

Tests Unitaires

• Pour lancer les TU, il suffit de lancer la commande make test.
• Le code source des tests se trouve dans le répertoire regovar/tests.
• Les fichiers d'inputs utilisés pour les tests se trouvent dans regovar/tests/inputs.
• Les tests doivent couvrir à minima :
  • L'ensemble des opérations de base (CRUD) du model
  • Les fonctionnalités des managers du core
• À noter que lorsqu'on lance les tests via le makefile, une nouvelle base de données est créée afin de ne pas polluer ou corrompre la base de données utilisée par le développeur.

Coverage

Nous utilisons le module Python coverage pour calculer la couverture des tests et générer le rapport au format xml, ensuite on envoie ces données à l'outil codacy qui permet de centraliser et de publier l'information via GitHub.

pip install coverage
pip install codacy-coverage
coverage run tests.py
coverage xml
export CODACY_PROJECT_TOKEN={token codacy du projet Regovar}
python-codacy-coverage -r coverage.xml

Travis

Nous utilisons travis qui s'occupe de tester que tout fonctionne correctement après chaque commit sur la branche master. Après avoir construit une machine virtuelle répondant aux besoins de Regovar, il exécute pour nous les TU ainsi que la génération du rapport de couverture.

Gestion des erreurs

Outils du Core

• Vous trouverez dans regovar/core/framework/common.py les outils de base :
  • Les logs avec les 3 méthodes pour chaque niveau d'alerte : log, war et err (accepte les exceptions en argument).
  • Les logs volumineux avec la méthode log_snippet.
  • La classe RegovarException qui se chargera automatiquement d'écrire les logs.
• Erreurs gérées :
  • Liste des erreurs associées à leur code dans le fichier : regovar/core/framework/errors_list.py.
  • Associer une erreur à un code permet ensuite de remonter et fournir ce code à l'utilisateur non technique qui pourra demander du support ou trouver la doc en ligne concernant cette erreur.
  • Il faut pour cela lever une exception de type RegovarException en indiquant en paramètre le code d'erreur.
  • Penser à tenir à jour le fichier regovar/core/framework/errors_list.py ainsi que les fiches d'aide correspondant à chaque erreur dans le répertoire regovar/api_rest/templates/errors/.

Outils de l'API Rest

• Dans le fichier regovar/api_rest/rest.py.
• Les méthodes rest_error ou rest_exception doivent être systématiquement utilisées pour remonter une erreur aux clients.
• Ces deux méthodes se chargent de formater correctement la réponse json en cas d'échec.

Convention de codage

Nomenclature et règles de codage

Pour ceux qui connaissent, nous respectons la convention Python PEP8. Pour ceux qui ont la flemme de tout lire, au moins lire le résumé par Sam&Max.
Cependant, nous tolérons les entorses suivantes :

• sauter plusieurs ligne entre définition de class ou de fonction car ça permet d'avoir un code plus aéré ;
• avoir des lignes de code faisant plus de 80 caractères.

Organisation du code

L'organisation du code est normalement suffisamment simple et propre pour qu'on puisse facilement s'y repérer. En cas de doute, merci de demander à l'équipe du projet. Pour plus de détails, il est recommandé de lire l'ensemble des documents de la section DEVELOPPEUR.