From ff030587c55067e2a50a7b33236b13ca47e35ba0 Mon Sep 17 00:00:00 2001 From: klafyvel Date: Tue, 23 Apr 2019 16:19:29 +0200 Subject: [PATCH] Create Dev Documentation/Contributing --- Dev-Documentation/Contributing.md | 174 ++++++++++++++++++++++++++++++ 1 file changed, 174 insertions(+) create mode 100644 Dev-Documentation/Contributing.md diff --git a/Dev-Documentation/Contributing.md b/Dev-Documentation/Contributing.md new file mode 100644 index 0000000..452c148 --- /dev/null +++ b/Dev-Documentation/Contributing.md @@ -0,0 +1,174 @@ +[TODO : translate this] + +# À propos de ce document + +Afin de pouvoir assurer une évolution la plus saine possible du projet, ce +document a pour but de donner les comportements attendus lors d'une +contribution à Re2o. Il s'inspire notamment de : + +- A successful Git branching model ([https://nvie.com/posts/a-successful-git-branching-model/](https://nvie.com/posts/a-successful-git-branching-model/)); +- Les comptes rendus des différentes réunions autour du projets. + +# Développement + +## Code source + +Le code source doit être en anglais, respecter la PEP8 +([https://www.python.org/dev/peps/pep-0008/](https://www.python.org/dev/peps/pep-0008/)). +Il existe des outils qui vous permettent de rendre votre code *PEP8-compliant* +de manière presque autonome. Respecter la PEP20 +([https://www.python.org/dev/peps/pep-0020/](https://www.python.org/dev/peps/pep-0020/)) +est plus qu'une bonne idée. + +## Documentation + +Il est impératif d'écrire de la documentation pour que le projet soit pérenne. +La langue à privilégier est là encore l'anglais. + +On se réfèrera à cette page : +([https://gitlab.federez.net/federez/re2o/wikis/Dev%20Documentation/Documentation](https://gitlab.federez.net/federez/re2o/wikis/Dev%20Documentation/Documentation)) +pour plus de précisions sur la documentation. + +## Interface + +L'interface utilisateur doit être intuitive. Cette notion étant difficile à +évaluer, la meilleure façon de s'en assurer et de faire tester l'interface à un +maximum de personnes, de préférence concernées par l'interface en question. Par +exemple, un utilisateur lambda devrait tester la page de profil, et pas +uniquement un administrateur ou un développeur chevronné. + +La langue de l'interface doit être à minima en anglais, l'idéal étant d'ajouter +la traduction le plus tôt possible. + +## Migrations + +Afin de lutter contre la complexification de l'arbre des migrations, il est +fortement conseillé de fusionner un maximum de migrations ensemble. + +# Utilisation du Gitlab + +Le gitlab du projet se trouve ici : [https://gitlab.federez.net/federez/re2o](https://gitlab.federez.net/federez/re2o). + +## Structure des branches + +### Master +Master est la branche stable. ***Il est interdit de `push` directement sur +master, à l'exeption des commits de merge***. Les *Merge requests* autorisées +doivent venir d'une branche de *release* ou de *hotfix* et avoir été validées +par 2 contributeurs (si possible non impliqués dans la phase de développement) +pour être mergées. + +#### Merge dans master + +Afin de garder un historique des commits propre, l'utilisation de `merge` avec +l'option `--no-ff` semble une bonne solution. Cela implique de ne pas passer +par le bouton `Merge` du Gitlab. Les commits de merge dans master doivent avoir +la forme suivante : + +``` +Release : [: ] +``` +ou +``` +Hotfix : +``` + +De cette manière on peut facilement annuler un merge introduisant un bug. + +### Dev +`Dev` est la branche de développement. Toutes les branches de *feature* et de +*release* doivent partir de dev. + +Lors du merge d'une *release* dans master, il faut également merger ladite +release dans dev. + +#### Merge dans dev + +Le merge dans dev doit être précédé par la création d'une *Merge Request*. Soit +il s'agit du merge dans master d'une *release*, soit il s'agit de l'intégration +d'une *feature*. Dans le deuxième cas, il faut créer une MR sur le Gitlab, qui +devra avoir été revue par deux contributeurs avant d'être fusionnée. On peut +pour cela utiliser le bouton prévu à cet effet sur l'interface de la MR dans +Gitlab. + +### Branches de *release* +Les branches de release préparent le merge dans master de la branche dev. On +peut créer une branche de *release* dès lors que la *milestone* associée +([https://gitlab.federez.net/federez/re2o/milestones](https://gitlab.federez.net/federez/re2o/milestones)) +est complétée ou que les modifications à effectuer sont 'mineures' (traduction, +retouche de design, etc...). Cela permet à la branche dev de continuer +d'avancer, même si la *release* a besoin de quelques retouches. + +Il semble bon de nommer ces branches selon la convention suivante : +``` +release- +``` + +### Branches de *feature* +Dans l'idéal, une feature doit être précédée de la création d'une *issue* +([https://gitlab.federez.net/federez/re2o/issues](https://gitlab.federez.net/federez/re2o/issues)), +avec les bons tags, notamment `To Do`, `Doing` et `Done`, afin de pouvoir +suivre l'évolution du projet sur cette page : +[https://gitlab.federez.net/federez/re2o/boards](https://gitlab.federez.net/federez/re2o/boards). + +Si votre *feature* nécessite certaines manipulations de la part de l'utilisateur, +ou introduit des notions non triviales, il ne faut surtout pas hésiter à éditer +le fichier `CHANGELOG.md` ainsi que créer les pages +[wiki](https://gitlab.federez.net/federez/re2o/wikis/home) nécessaires. + +Le nom de la branche de *feature* devrait être explicite. Bien qu'il n'y ait pas +de restriction sur le format des messages de commits, essayez de les garder le +plus clair possible. + +Les branches de *feature* ont vocation à être mergées dans dev. Pour cela +utilisez des merge requests, en faisant bien attention à la branche cible. La +merge request peut-être utilisée afin d'obtenir des retours. Pour cela préfixez +le nom de la merge request par `WIP :`. + +### Branches de *hotfix* +Malgré la relecture attentive et les efforts de chacuns, des bugs peuvent +réussir à se glisser en production. Afin de les corriger rapidement, il faut +créer une branche de *hotfix*. Ces branches sont destinées à être mergées dans +master et dans dev en suivant les règles établies pour le merge dans ces +branches. + +Une bonne manière de nommer ces branche est +``` +hotfix- +``` + +## Fusion de branches + +Afin d'éviter des conflits lors de fusions il est préférable de rebaser la +branche cible dans la branche source. + +## Utilisation des issues + +Les issues permettent de remonter les problèmes et de proposer de nouvelles +features. L'utilisation des tags à disposition est fortement encouragée. + +# Communication et vie du projet + +Le projet dispose de plusieurs moyens de communication : + +- [Le Gitlab](https://gitlab.federez.net/federez/re2o) avec les issues pour +les propositions détaillées de nouvelles *features* et les rapports de bugs; +- Le chan IRC (`irc.rezosup.org` sur le cannal `#re2o`), bridgé avec cette +[conversation Telegram](https://t.me/joinchat/Gv_Hw1Mu9L7pu-VIzN9L9Q); +- La mailing-list [re2o@federez.net](mailto:re2o@federez.net). + +Pour tout ces canaux de discussion, les règles de savoir vivre usuelles sont +en vigueur. En particulier, il est attendu des participants : + +- Qu'ils respectent les idées des autres, et les laissent les exprimer; +- Qu'ils encouragent la participation des nouveaux venus au projet. Cela +signifie en particulier qu'il n'existe pas de question stupide, que si +une question revient de manière récurrente, alors il est nécessaire +d'éclaircir la partie du projet concernée et que les nouveaux venus doivent +être guidés s'ils le souhaitent; +- Qu'ils soient capables de se retenir de participer s'ils pensent que leur +participation ne sera pas constructive. En effet ce projet nous tient tous +à cœur, et il peut nous arriver de défendre une idée au delà du raisonnable +car elle nous semble vitale. +- Qu'ils prennent du plaisir à participer à ce projet communautaire et +instructif. \ No newline at end of file