Contribuer à Zeste de Savoir

Avant de commencer…

Vérifiez que vous avez un compte Github.
Créez le ticket correspondant à votre travail s’il n’existe pas. (Cette étape peut être omise pour des corrections mineures.)
- Vérifiez que vous avez la dernière version du code.
- Décrivez clairement votre problème, avec toutes les étapes pour le reproduire.
Attribuez-vous votre ticket. 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 le ticket, ajoutez simplement un commentaire clair dans celui-ci (tel que « Je prends »).
Forkez le dépôt et installez l’environnement, comme décrit ici.

Contribuer à Zeste De Savoir

Créez une branche pour contenir votre travail.
Faites vos modifications.
Ajoutez un test pour votre modification. Seules les modifications de documentation et les réusinages n’ont pas besoin de nouveaux tests.
Assurez-vous que vos tests passent en utilisant la commande make test-back (voyez la page dédiée pour plus de détails). Lancer la commande sur tous les tests du site risque de prendre un certain temps et n’est pas nécessaire : les tests seront de toute manière lancés de manière automatisée sur votre pull request.
Si vous avez modifié les modèles (les fichiers models.py), n’oubliez pas de créer les fichiers de migration : python manage.py makemigrations.
Poussez votre travail et faites une pull request.
Si votre travail nécessite des actions spécifiques lors du déploiement, précisez-les dans le corps de votre pull request. Elles seront ajoutées au changelog par le mainteneur qui effectuera le merge.

Quelques bonnes pratiques

Respectez les conventions de code de Django, ce qui inclut la PEP 8 de Python.
Le code et les commentaires sont en anglais.
Le workflow Git utilisé est le Git flow, qui est détaillé ici. En résumé :
- 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 !
Faites des messages de commit clairs et en français.
Il n’y a aucune chance que votre pull request soit acceptée sans son test associé.
Votre test doit échouer sans votre modification, et réussir avec.

Les bonnes pratiques pour les PR et les commits

Les Pull Requests

Lors de l’ouverture d’une PR, la zone de texte sera pré-complété avec les informations essentielles à apporter à votre PR. Utilisez ce gabarit pour rédiger votre message.

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, comme python manage.py migrate --fake-initial, python manage.py loaddata fixture/*.yaml ou yarn run build.

Mise à jour d’une Pull Request : rebase

Au fil de l’avancement de votre PR, ou juste avant de la fusionner, il peut vous être demandé de rebaser (ou rebase). Cela permet de mettre à jour la branche de votre PR avec la toute dernière version de la branche principale du dépôt.

C’est une opération assez simple, et très utile pour s’assurer que votre modification s’intègre toujours bien avec la toute dernière version du site (si d’autres contributeurs ont changé quelque chose, typiquement). Elle a l’avantage, par rapport à une classique fusion (git merge), d’intégrer les commits naturellement dans l’historique, sans en ajouter de supplémentaire inutile.

Pour rebase en ligne de commande, utilisez la commande git pull --rebase upstream dev (c’est tout). Si vous utilisez une interface graphique pour git, la marche à suivre dépendra de cette interface.

Avertissement

Si git vous informe qu’il y a des conflits lors du rebase, cela signifie que des parties du code ont été modifiées à la fois par les autres contributeurs et par vous-même. Pas de panique ! Corriger un conflit est assez simple. Git va, pour chaque conflit, vous montrer votre version et la version des autres contributeurs côte à côte dans le fichier concerné, et ce sera à vous de décider ce que vous gardez (votre version, celle des autres, ou un savant mélange des deux). Concrètement, pour chacun des fichiers que git indique comme en conflit, vous devez :

ouvrir le fichier, chercher les marques qu’a laissé git à l’intérieur, et résoudre le conflit en choisissant quel bout garder (tout en retirant les marques de conflit de git — à la fin, le fichier doit être “normal”, comme si git n’était jamais passé par là) ;
marquer les conflits du fichier comme corrigés (git add <path> en ligne de commande, et probablement quelque chose comme “Marquer comme résolu” en GUI) ;
continuer le rebase (git rebase --continue en ligne de commande, “Continuer le rebase” ou similaire en GUI).

Vous devez ensuite publier sur GitHub avec un force-push (git push --force), car rebase réécrit l’historique (si vous oubliez, vous obtiendrez une erreur et git refusera l’opération). Ça ne pose aucun problème ici — c’est l’un des cas d’usage légitime du force-push, et vous ne le faites que sur votre propre branche.

Note

Pour pouvoir rebaser, il vous faut avoir défini une remote upstream pointant vers le dépôt principal de ZdS (la remote origin devant pointer vers votre fork), de la façon suivante : git remote add upstream https://github.com/zestedesavoir/zds-site.git.

Cette opération n’est nécessaire qu’une seule fois au début, pour tous les rebases que vous ferez sur votre fork.

Il est également possible de mettre la branche à jour sur GitHub en bas de la page de la PR, mais GitHub créé un commit de fusion sans faire de rebase.

Les commits

Pour les commits, nous suivons le même ordre d’idée que les standards Git.

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.
Bien que le code soit en anglais, le commit doit être de préférence en français.
Vous pouvez également (c’est d’ailleurs conseillé) référencer l”issue que vous corrigez.
Un commit doit être atomique ; il fixe / implémente une chose et le fait bien.

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