More on contributing + create indivual pages

Aurélien Delobelle 2018-09-30 15:35:40 +02:00
parent 96010ff790
commit 0c00fe8300
4 changed files with 260 additions and 61 deletions

51
coding-style.md Normal file

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

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

9
testing.md Normal file

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

@ -1,5 +1,14 @@
Architecture du dépôt [[_TOC_]]
=====================
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 : Actuellement, il y a trois branches protégées :
- `Production` qui est la version en ligne sur www.cof.ens.fr, seuls les - `Production` qui est la version en ligne sur www.cof.ens.fr, seuls les
@ -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 Toute autre branche est gérée librement par les personnes qui travaillent
dessus. 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``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 Membres
======= -------
Il y a trois types de contributeurs à cof-geek. 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 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 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. 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 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 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 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 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 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 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` sans vergogne ! Ils doivent tout de même être reviewés par un autre
Master, voir la section Merge requests. 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).