More on contributing + create indivual pages
Aurélien Delobelle
parent
96010ff790
commit
0c00fe8300
4 changed files with 260 additions and 61 deletions
51
coding-style.md
Normal file
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
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
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.
|
||||
231
workflow.md
231
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).
|
||||
|
|
|
|||
Loading…
Reference in a new issue