workflow.md

-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).