CONTRIBUTING.md

ENGLISH VERSION

Les contributions externes sont les bienvenues !

Avant de réaliser...

1. Vérifiez que vous avez un compte Github

2. Créez votre issue si elle n'existe pas

   • Vérifiez que vous avez la dernière version du code
   • Décrivez clairement votre problème, avec toutes les étapes pour le reproduire

3. Attribuez-vous votre issue. C'est important pour éviter de se marcher dessus. Si vous n'êtes pas dans l'organisation et donc que vous ne pouvez pas vous attribuer directement l'issue, il vous suffit d'ajouter un commentaire clair dans celle-ci (comme "Je prends"), et elle sera marquée comme "In progress").

4. Forkez le dépôt

Contribuer au site

1. Créez une branche pour contenir votre travail
2. Faites vos modifications
3. Ajoutez un test pour votre modification. Seules les modifications de documentation et les réusinages n'ont pas besoin de nouveaux tests
4. Assurez-vous que l'intégralité des tests passent
5. Si votre travail nécessite des actions spécifiques lors du déploiement, précisez-les dans le fichier update.md.
6. Poussez votre travail et faites une pull request

Quelques bonnes pratiques

• Le code et les commentaires sont en anglais

• Le workflow Git utilisé est le Git flow. En détail :

  • Les arrivées fonctionnalités et corrections de gros bugs hors release se font via des PR.
  • Ces PR sont unitaires. Aucune PR qui corrige plusieurs problèmes ou apporte plusieurs fonctionnalité ne sera accepté ; la règle est : une fonctionnalité ou une correction = une PR.
  • Ces PR sont mergées dans la branche dev (appelée develop dans le git flow standard), après une QA légère.
  • Pensez à préfixer vos branches selon l'objet de votre PR : hotfix-XXX, feature-XXX, etc.
  • La branche prod (appelée master dans le git flow standard) contient exclusivement le code en production, pas la peine d'essayer de faire le moindre commit dessus !

• Votre test doit échouer sans votre modification, et réussir avec

• Faites des messages de commit clairs

• Il n'y a aucune chance que votre pull request soit acceptée sans son test associé

Les bonnes pratiques pour les PR et les commits

Les Pull-Requests

• Lors de l'ouverture d'une PR, respectez le template suivant :

  | Q                             | R
  | ----------------------------- | -------------------------------------------
  | Correction de bugs ?          | [oui|non]
  | Nouvelle Fonctionnalité ?     | [oui|non]
  | Tickets (_issues_) concernés  | [Liste de tickets séparés par des virgules]

• Ajoutez des notes de QA (Quality Assurance). Ces notes doivent permettent à un testeur de comprendre ce que vous avez modifié, ce qu'il faut tester en priorité et les pièges auxquels il doit s'attendre et donc sur lesquels porter une attention particulière. Précisez tout particulièrement s'il est nécessaire d'effectuer une action de gestion préalable.

Les commits

• Pour les commits, nous suivons le même ordre d'idée des standards Git, à savoir :

  • La première ligne du commit ne doit pas faire plus de 50 caractères
  • Si besoin, complétez votre commit via des commentaires, en respectant une limite de 70 caractères par ligne
  • Vous pouvez également (c'est d'ailleurs conseillé) de référencer l'issue que vous fixez
  • Un commit doit être atomique ; il fixe / implémente une chose et le fait bien

• Essayez d'éviter les commits dits inutiles (fix previous commit, ...). Si vous en avez dans votre pull-request, on vous demandera probablement de faire un squash de vos commits.

N'hésitez pas à demander de l'aide, et bon courage !

============================================ ENGLISH

External contributions are welcome!

Before jumping into the project

1. Verify that you have a Github account

2. Create your issue if it does not exist

   • Make sure you have the latest project version
   • Describe clearly your problem and the sequence to reproduce it

3. Flag yourself on the issue. It is important for good workflow. If you are not a part of the organization, thus can't flag yourself on the issue, you just need to add "Working on it" and the issue will mark as "In progress".

4. Fork the repository

Contribute to the website

1. Create a branch
2. Work on it
3. Test your code! Only documentation and refactoring modifications does not need to have new tests.
4. Make sure the tests are successful
5. If your work need specific tasks for deployment, make sure to notify it in update.md.
6. Push and create a pull request

Good practices

• Code and comments are in English

• Follow Git workflow .

  • Functionality and big bugs are made via Pull Requests
  • One bug/functionality per pull request, no exception!
  • Those pull requests are merged into the dev branch (Git flow : develop branch)
  • Name the branch based on the modification : hotfix-XXX, feature-XXX, etc.
  • The branch prod (Git flow : master branch) contains the production code. Do not try to commit on this branch !

• Your test must fail before your edits and then pass with them

• Make thorough commit comment

• No test, no pull request

Good practices : Pull Request/commit

Pull-Requests

• PR template :

  | Q                             | R
  | ----------------------------- | -------------------------------------------
  | Bug fix ?                     | [yes|no]
  | New functionality ?           | [yes|no]
  | Tickets (_issues_) reference  | [List of ticket seprated by ;]

• Add QA comments. Those comments help to comprehend what have been modified, what must be tested and the more risky part of the code. Make sure to comment if a setup is needed beforehand.

Commits

• For commits, we follow the Git philosophy :

  • The first line must not be more than 50 characters
  • If needed, complete your commit by adding comments (maximum of 70 characters per following lines)
  • Reference the issue associated with the fix
  • One fix, and one good fix only, per commit (atomic)

• Make sure your pull request does not have any useless commits (e.g. fix previous commit, ...). If you have any, squash them.

Don't hesitate to ask for help, good luck!