diff --git a/coding-style.md b/coding-style.md new file mode 100644 index 0000000..7ad9bb4 --- /dev/null +++ b/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. diff --git a/home.md b/home.md index b741bcc..9819823 100644 --- a/home.md +++ b/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) \ No newline at end of file +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) diff --git a/testing.md b/testing.md new file mode 100644 index 0000000..025ed28 --- /dev/null +++ b/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. diff --git a/workflow.md b/workflow.md index 86f025a..1111d6c 100644 --- a/workflow.md +++ b/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).