More on contributing + create indivual pages

coding-style.md

@@ -0,0 +1,51 @@
+Conventions de développement
+============================
+
+Cette page établit une liste de contraintes à respecter pour que du code soit
+intégré à GestioCOF.
+Elles semblent nécessaires pour plusieurs raisons, comme l'amélioration de la
+lisibilité du code et une plus grande simplicité à travailler sur un projet
+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*.
+
+[[_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.  
+Une rapide recherche du nom de votre éditeur et de l'extension devrait vous
+mettre sur une bonne voie.
+
+Certains d'entre eux feront peut-être parties intégrantes du processus de
+développement en étant ajoutés à la CI (intégration continue).  
+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.
+
+### flake8
+
+Le code Python devrait être validé par [flake8](http://flake8.pycqa.org/en/latest/).
+Ce n'est pas une nécessité mais ça peut être une bonne habitude à prendre.
+Il vérifie, entre autres, que les conventions de la [PEP8](https://www.python.org/dev/peps/pep-0008/)
+sont bien respectées.
+
+À noter : Django est testé avec flake8 et
+[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/)
+content, les messages offerts par ce plugin sont parfois utiles pour détecter
+des erreurs.

home.md

@@ -1,9 +1,29 @@
-[Comment on fonctionne ?](workflow)
+Salut à toi !
+=============
 
-[Utiliser la VM Vagrant](vagrant)
+Utilisateur
+-----------
 
-[Accéder à l'interface administrateur de gestioCOF](gestiocof-admin)
+Pour une ébauche de documentation à l'attention des utilisateurs de GestioCOF,
+c'est [ici](user-doc/home).
 
-[Commandes django utiles](manage.py)
+Développeur
+-----------
 
-[Documentation utilisateur](user-doc/home)
+Vous pouvez aussi trouver des informations, parfois plus à jour, dans le
+[README](https://git.eleves.ens.fr/cof-geek/gestioCOF/blob/master/README.md).
+
+Votre premier projet pourrait être de fusionner ces deux sources
+d'informations, en ne laissant que des liens du README vers ce wiki.
+
+### Contribuer
+
+- [Workflow / Git](workflow)
+- [Conventions de développement](coding-style)
+- [Tests](testing)
+
+### Environnement de développement
+
+- [Utiliser la VM Vagrant](vagrant)
+- [Accéder à l'interface administrateur de gestioCOF](gestiocof-admin)
+- [Commandes django utiles](manage.py)

testing.md

@@ -0,0 +1,9 @@
+Tests
+=====
+
+On commence (youpi !) à tester notre code. C'est une bonne habitude à prendre
+d'ajouter des tests quand on développe une nouvelle fonctionnalité, si vous avez
+du mal demandez et quelqu'un vous aidera.
+Une autre bonne habitude à prendre : quand on résout un bug il faudrait
+systématiquement ajouter un test correspondant au bug pour s'assurer qu'il
+n'arrivera plus.

workflow.md

@@ -1,7 +1,16 @@
-Architecture du dépôt
+[[_TOC_]]
-=====================
 
-Actuellement, il y a trois branches protégées : 
+
+Quelques mots sur le dépôt
+==========================
+
+Première chose : il est stocké sur une machine de l'ENS, et on y accédera par
+l'installation de GitLab gérée par les (gourous)[https://www.tuteurs.ens.fr/meta/gourous.html].
+
+Architecture
+------------
+
+Actuellement, il y a trois branches protégées :
 - `Production` qui est la version en ligne sur www.cof.ens.fr, seuls les
   webmasters touchent à ça.
 - `master`, la version la plus récente du projet. De temps en temps, on merge
@@ -11,73 +20,25 @@ Pour affecter ces branches, il faut passer par une merge request (cf plus bas).
 Toute autre branche est gérée librement par les personnes qui travaillent
 dessus.
 
-Merge requests
-==============
-
-Le fonctionnement des dépots cof-geek se fait par merge requests, qui doivent
-être reviewées par une personne expérimentée (= Master, cf plus bas) qui n'a pas
-participé à l'écriture du code. En pratique pour faire une merge request, après
-avoir cloné le dépot, il faut faire une branche séparée avec
-`git checkout -b login/ma-branche` où `login` est votre pseudo et `ma-branche`
-un nom simple décrivant les modifications que vous souhaitez apporter. Ensuite
-faites vos modifications, puis poussez sur le GitLab. Là vous pouvez aller sur
-l'interface Web et cliquer sur le bouton "faire une merge request" qui apparaît.
-
-Une fois la merge request effectuée, un Master lira et commentera votre code.
-Une merge request est une discussion entre l'auteur du code et le reviewer, ne
-vous pliez pas juste aux demandes du reviewer, votre point de vue compte ! Par
-ailleurs c'est plus à vous de modifier le code qu'au reviewer, mais cela dépend
-des situations.
-
-N'hésitez pas à regarder les merge requests des autres, même sans être master,
-toute remarque constructive est bonne à prendre. De plus, c'est une bonne façon
-de se familiariser avec le code (et pourquoi pas devenir master un jour ;D).
-
-### Quelques outils pour review son code ou celui des autres
-
-- [Pylint](https://www.pylint.org/) fait un tas de vérifications et permet
-  notamment d'éviter un certain nombre d'erreurs.
-- [Flake8](https://pypi.python.org/pypi/flake8) vérifie que les conventions  de
-  la [PEP8](https://www.python.org/dev/peps/pep-0008/) (et quelques autres) sont
-  bien respectées. Ce n'est pas une nécessité mais ça peut être une bonne
-  habitude à prendre. À noter: Django est testé avec flake8 et recommande son
-  usage
-  (https://docs.djangoproject.com/en/1.11/internals/contributing/writing-code/coding-style/)
-
-
-Tests
-=====
-
-On commence (youpi !) à tester notre code. C'est une bonne habitude à prendre
-d'ajouter des tests quand on développe une nouvelle fonctionnalité, si vous avez
-du mal demandez et quelqu'un vous aidera.
-Une autre bonne habitude à prendre : quand on résout un bug il faudrait
-systématiquement ajouter un test correspondant au bug pour s'assurer qu'il
-n'arrivera plus.
-
-
 Membres
-=======
+-------
 
 Il y a trois types de contributeurs à cof-geek.
 
-Extérieurs
+### Extérieurs
-----------
 
 Les extérieurs sont des gens avec un compte sur le GitLab mais non membres de
 cof-geek. Ils peuvent contribuer en forkant le dépot et en faisant une merge
 request. Ils n'ont aucun droit particulier sur le dépôt.
 
-Developer
+### Developer
----------
 
 Le titre de Developer indique un membre de cof-geek, c'est-à-dire quelqu'un
 présent sur la ML et qui contribue activement (ou pas) du code. Les Developers
 peuvent accéder au dépôt commun, créer des branches, etc : ce sont donc des gens
-en qui une certaine confiance est placée. 
+en qui une certaine confiance est placée.
 
-Master
+### Master
-------
 
 Les membres possédant le titre de Master sont des gens qui connaissent bien au
 moins une partie du code. Ils ont quelques droits supplémentaires par rapport
@@ -86,3 +47,161 @@ aux Developers ; en particulier ils peuvent modifier la branche principale
 n'est pas une raison suffisante pour pusher ses changements sur la branche
 `master` sans vergogne ! Ils doivent tout de même être reviewés par un autre
 Master, voir la section Merge requests.
+
+
+Contribuer
+==========
+
+Avant de vous y mettre, vous devez [installer GestioCOF](https://git.eleves.ens.fr/cof-geek/gestioCOF#installation)
+sur votre machine.
+
+Voici un résumé rapide de ce que nous voyons dans cette section.
+
+```shell
+# Créer une branche, depuis master
+$ git checkout -b login/ma-branche
+
+# Effectuer vos modifications
+...
+
+# Valider les tests
+$ python manage.py test
+
+# Versionner vos modifications
+$ git add .
+$ git commit -m "message de commit"
+
+# Publier vos modifications
+# La première fois:
+$ git push -u origin login/ma-branche
+# Les fois suivantes:
+$ git push
+
+# Ouvrir une MR sur GitLab: https://git.eleves.ens.fr/cof-geek/gestioCOF/merge_requests/new
+```
+
+Cette partie fait usage de [git](https://git-scm.com/). Vous pouvez consulter
+[ce guide](https://githowto.com/) pour vous préparer. Pas d'inquiétude
+cependant, les principales commandes seront rappelées ici.
+
+
+Créer une branche
+-----------------
+
+Après vous être saisi ou vu attribuer un ticket, vous pouvez passer au
+développement. Pour ça, vous devez commencer par créer une nouvelle branche qui
+recevra vos modifications.
+
+Les modifications devront être intégrées à la branche `master`, c'est pourquoi
+la nouvelle branche doit partir de celle-ci.
+
+```shell
+# Depuis la racine de gestioCOF
+# Assurons-nous de partir de la branche 'master'
+$ git checkout master
+# Création d'une branche nommée 'login/ma-branche'
+$ git checkout -b login/ma-branche
+```
+
+`login/ma-branche` est le nom de la nouvelle branche. Ce format est une
+convention que nous utilisons. `login` peut être le pseudo de votre choix,
+comme votre clipper, et `ma-branche` devrait indiquer le sujet que vous allez
+traiter.
+
+À titre d'exemple et d'information, Vous pouvez trouver la liste des branches
+de GestioCOF par [ici](https://git.eleves.ens.fr/cof-geek/gestioCOF/branches).
+
+
+Effectuer vos modifications
+---------------------------
+
+Saisissez-vous d'un éditeur de texte : Notepad++, Atom, VSCode, Vim,
+SublimeText...
+
+Et c'est le moment de se lancer.
+
+- Faîtes vos modifications (avez-vous lu [nos conventions](coding-style) ?)
+- Écrivez, éventuellement, des tests ([plus d'informations](testing))
+- Validez les tests: `python manage.py test`
+
+À tout moment, n'hésitez pas à poser des questions aux membres de `cof-geek`
+plus expérimentés, à consulter la documentation des outils que nous utilisons
+([Django](https://docs.djangoproject.com/en/1.11/),
+[Python](https://docs.python.org/3.5/)), et à utiliser votre moteur de
+recherche sur Internet préféré !
+
+**Tant que faire se peut,** les modifications d'une MR ne doivent concerner
+**qu'un seul sujet**. On préférera aussi les "petites" MR, c'est à dire contenant
+peu de modifications, donc plus faciles à review.
+
+
+Enregistrer et publier vos modifications
+----------------------------------------
+
+Pour voir la **liste des fichiers modifiés**, utiliser la commande :
+
+```shell
+$ git status
+```
+
+Vous devez ensuite **choisir les modifications** que vous souhaitez ajouter avec
+`git add`. En voici un exemple d'utilisation :
+
+```shell
+$ git add file1.py path/to/file2.html
+```
+
+Si toutes les modifications sont à ajouter, vous pouvez plus simplement :
+
+```shell
+$ git add .
+```
+
+Vous pouvez consulter les modifications qui **s'apprêtent à être enregistrées**
+avec :
+
+```shell
+$ git diff --cached`
+```
+
+Une fois que vous êtes sûr, **enregistrez** les modifications dans une
+nouvelle version avec une courte description.
+
+```shell
+$ git commit -m "titre de commit"
+```
+
+**Pousser**, publier, vos modifications sur le dépôt distant (GitLab). Pour une
+branche qui n'a jamais été publiée, utilisez :
+
+```shell
+$ git push -u origin nom-branche
+```
+
+Les fois suivantes, `git push` suffira.
+
+
+Ouvrir une Merge Request sur GitLab
+-----------------------------------
+
+Rendez-vous sur notre GitLab pour [ouvrir une MR](https://git.eleves.ens.fr/cof-geek/gestioCOF/merge_requests/new).
+Sur cette page, sélectionner votre nouvelle branche en tant que "Source". La
+cible sélectionnée devrait déjà être `cof-geek/GestioCOF:master`.
+
+Si vous venez de pousser votre branche, vous devriez aussi avoir un message qui
+vous propose justement de faire ça.
+
+Passer à l'étape suivante et indiquer les informations utiles pour "review"
+votre Merge Request : contexte, lien vers une issue concernée, les changements
+majeurs effectués et toutes remarques à partager.
+
+Une fois la merge request effectuée, un Master lira et commentera votre code.
+Une merge request est une discussion entre l'auteur du code et le reviewer, ne
+vous pliez pas juste aux demandes du reviewer, votre point de vue compte !
+
+Par ailleurs c'est plus à vous de modifier le code qu'au reviewer, mais cela
+dépend des situations. Vous devrez ainsi reprendre les deux étapes précédentes.
+
+N'hésitez pas à regarder les merge requests des autres, même sans être master,
+toute remarque constructive est bonne à prendre. De plus, c'est une bonne façon
+de se familiariser avec le code (et pourquoi pas devenir master un jour ;D).