coding-style.md

@@ -10,17 +10,23 @@ collaboratif.
 Ces contraintes ne devraient pas être des freins ! Si vous éprouvez des
 difficultés à les appliquer, placez votre attention sur la réalisation de votre
 but initial. Quelqu'un, ou vous-même, pourra toujours repasser un peu plus
-tard pour vous aider à *peaufiner*.
+tard pour vous aider à [*peaufiner*](https://www.youtube.com/watch?v=wf-BqAjZb8M).
+
+Ceratins des outils mentionnés ci-dessous peuvent être installés depuis
+gestioCOF avec:
+
+    pip install -r requiments-devel.txt
 
 [[_TOC_]]
 
+
 Linters
 -------
 
 Commençons par les conventions les plus simples à respecter : celles mises en
 œuvre par des programmes externes.  
-Ils peuvent généralement être intégrés facilement à votre éditeur de texte,
-nativement parfois, par l'installation d'extensions sinon.  
+Ces outils peuvent généralement être intégrés facilement à votre éditeur de
+texte, nativement parfois, par l'installation d'extensions sinon.  
 Une rapide recherche du nom de votre éditeur et de l'extension devrait vous
 mettre sur une bonne voie.
 
@@ -30,6 +36,66 @@ Pour savoir ce qu'il se passe dans la CI, consultez le dernier
 [gitlab-ci.yml](https://git.eleves.ens.fr/cof-geek/gestioCOF/blob/master/.gitlab-ci.yml)
 du projet.
 
+### black
+
+[black](https://github.com/ambv/black) est le "uncompromising Python code
+formatter". Il applique des corrections pour rendre le code PEP8-compliant et
+va au-delà.
+
+Les changements effectués sont déterministes et seront donc les mêmes peu
+importe la machine où il est utilisé. Les diffs des MRs s'en trouvent réduits
+et des conflits de fusion sont ainsi évités.
+
+Pour formatter le code du projet entier, utilisez:
+
+    black .
+
+Et sans effectuer de modifications mais en affichant les changements prévus:
+
+    black --check --diff .
+
+Vous pouvez indiquer un ou plusieurs chemins en particulier:
+
+    black --check --diff bda/
+
+Un hook git de pre-commit peut être installé (voir les instructions d'installation
+de gestioCOF) pour formatter automatiquement vos modifications avec black.  
+Notez que black requiert la version 3.6 de Python au minimum.  
+Des modifications pourront être effectuéees au moment de commit, et devront
+être ajoutées au contenu à commiter.  
+Si le programme n'est pas trouvé sur votre machine, ce check sera ignoré.
+Attention cependant, l'intégration continue pourrait alors échouer, auquel cas
+on peut vous aider.
+
+### isort
+
+[isort](https://github.com/timothycrosley/isort) est aussi un formatter de code
+Python, mais limité aux imports (`from ... import ...` et `import ...`).  
+Ces lignes suivent alors des règles de formatage identiques : tri par type
+d'imports, alphabétique, etc.  
+
+À nouveau cela permet d'éviter des conflits de fusion.
+
+Pour formatter le code du projet entier, utilisez:
+
+    isort --recursive bda cof gestioncof kfet provisioning shared utils
+
+Ou seulement certains répertoires:
+
+    isort --recursive cof
+
+Sans modifier les fichiers et en affichant les changements prévus:
+
+    isort --recursive --check-only --diff bda cof kfet
+
+Ce formatter est aussi lancé par le hook de pre-commit (si le hook et isort
+sont installés).  
+Des modifications pourront être effectuéees au moment de commit, et devront
+être ajoutées au contenu à commiter.
+Si le programme n'est pas trouvé sur votre machine, ce check sera ignoré.
+Attention cepedant, l'intégration continue pourrait alors échouter, auquel cas
+on peut vous aider.
+
 ### flake8
 
 Le code Python devrait être validé par [flake8](http://flake8.pycqa.org/en/latest/).
@@ -41,9 +107,6 @@ sont bien respectées.
 [recommande](https://docs.djangoproject.com/en/1.11/internals/contributing/writing-code/coding-style/)
 son usage.
 
-Celui-ci peut s'intégrer rapidement à votre éditeur de texte, vérifier dans le
-catalogue des extensions disponibles de celui-ci.
-
 ### pylint
 
 Bien que personne ne devrait vous en vouloir de ne pas rendre [Pylint](https://www.pylint.org/)