[[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 :
Productionqui 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 mergemastersurProduction. En théorie, dev.cof.ens.fr suit cette branche.
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.
Membres
Il y a trois types de contributeurs à cof-geek.
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
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.
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
aux Developers ; en particulier ils peuvent modifier la branche principale
(master). Ce sont eux qui mergent les merge request. Attention : être master
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 sur votre machine.
Voici un résumé rapide de ce que nous voyons dans cette section.
# 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. Vous pouvez consulter ce guide 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.
# 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.
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 ?)
- Écrivez, éventuellement, des tests (plus d'informations)
- 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,
Python), 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 :
$ git status
Vous devez ensuite choisir les modifications que vous souhaitez ajouter avec
git add. En voici un exemple d'utilisation :
$ git add file1.py path/to/file2.html
Si toutes les modifications sont à ajouter, vous pouvez plus simplement :
$ git add .
Vous pouvez consulter les modifications qui s'apprêtent à être enregistrées avec :
$ git diff --cached`
Une fois que vous êtes sûr, enregistrez les modifications dans une nouvelle version avec une courte description.
$ 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 :
$ 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.
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).