Contribuer sur GitHub¶

Ce guide s’adresse aux personnes qui veulent participer au développement de Flower mais qui n’ont pas l’habitude de contribuer à des projets GitHub.

Si vous êtes familier avec la façon dont on contribue sur GitHub, vous pouvez directement consulter notre getting started guide for contributors.

Mise en place du référentiel¶

Créer un compte GitHub et configurer Git
Git est un outil de contrôle de version distribué. Cela permet d’enregistrer l’histoire entière du codebase et chaque machine des développeurs. Il s’agit d’un logiciel qui doit être installé sur votre ordinateur local, vous pouvez suivre ce guide pour le configurer.

GitHub, lui-même, est une plateforme d’hébergement de code pour le contrôle des versions et la collaboration. Il permet à chacun de collaborer et de travailler de n’importe où sur des dépôts à distance.

Si ce n’est pas déjà fait, tu devras créer un compte sur GitHub.

L’idée derrière le flux de travail générique de Git et GitHub se résume à ceci : tu télécharges le code d’un dépôt distant sur GitHub, tu apportes des modifications localement et tu en gardes une trace à l’aide de Git, puis tu télécharges ton nouvel historique à nouveau sur GitHub.
Fourche le dépôt de Flower
Une branche est une copie personnelle d’un dépôt GitHub. Pour créer une pour Flower, vous devez naviguer vers https://github.com/flwrlabs/flower (tandis que connecté à votre compte GitHub) et cliquer sur le bouton Fork situé en haut à droite de la page.

Tu peux changer le nom si tu le souhaites, mais ce n’est pas nécessaire car cette version de Flower sera la tienne et se trouvera dans ton propre compte (c’est-à-dire dans ta propre liste de dépôts). Une fois créée, tu devrais voir dans le coin supérieur gauche que tu es en train de regarder ta propre version de Flower.
Clonage de ton dépôt forké
L’étape suivante consiste à télécharger le dépôt forké sur ta machine pour pouvoir y apporter des modifications. Sur la page de ton dépôt forké, tu dois d’abord cliquer sur le bouton Code à droite, ce qui te permettra de copier le lien HTTPS du dépôt.

Une fois que tu as copié le <URL>, tu peux ouvrir un terminal sur ta machine, naviguer jusqu’à l’endroit où tu veux télécharger le référentiel et taper :
$ git clone <URL>
Cela créera un dossier flower/ (ou le nom de votre branche si vous l’avez renommée) dans le répertoire actuel.
Ajouter l’origine
Tu peux ensuite aller dans le dossier du référentiel :
$ cd flower
Et ici, nous devrons ajouter une origine à notre dépôt.L’origine est le <URL> du dépôt fork distant.Pour l’obtenir, nous pouvons faire comme indiqué précédemment en allant sur notre dépôt fork sur notre compte GitHub et en copiant le lien.

Une fois que le <URL> est copié, nous pouvons taper la commande suivante dans notre terminal :
$ git remote add origin <URL>
Ajouter en amont
Maintenant, nous allons ajouter une adresse upstream à notre dépôt. Toujours dans la même racine, nous devons exécuter la commande suivante:
$ git remote add upstream https://github.com/flwrlabs/flower.git
Le schéma suivant explique visuellement ce que nous avons fait dans les étapes précédentes :

L’amont est l’adresse distante GitHub du dépôt parent (dans ce cas Flower), c’est-à-dire celui auquel nous voulons éventuellement contribuer et dont nous avons donc besoin d’un historique à jour. L’origine est simplement l’adresse distante GitHub du dépôt forké que nous avons créé, c’est-à-dire la copie (fork) dans notre propre compte.

Pour nous assurer que notre version locale du fork est à jour avec les dernières modifications du dépôt Flower, nous pouvons exécuter la commande suivante :
$ git pull upstream main

Mise en place de l’environnement de codage¶

Cela peut être réalisé en suivant ce getting started guide for contributors (notez que vous n’aurez pas besoin de cloner le dépôt). Une fois que vous serez capable d’écrire du code et de l’exécuter, vous pourrez finalement commencer à faire des modifications !

Apporter des changements¶

Avant de faire des changements, assure-toi que tu es à jour avec ton référentiel :

$ git pull origin main

Et avec le référentiel de Flower :

$ git pull upstream main

Créer une nouvelle branche
Pour rendre l’historique plus propre et plus facile à travailler, c’est une bonne pratique de créer une nouvelle branche pour chaque fonctionnalité/projet qui doit être mis en œuvre.

Pour ce faire, il suffit d’exécuter la commande suivante dans le répertoire du référentiel :
$ git switch -c <branch_name>
Apporter des modifications
Écris du bon code et crée de merveilleuses modifications à l’aide de ton éditeur préféré !
Teste et mets en forme ton code
N’oublie pas de tester et de formater ton code ! Sinon, ton code ne pourra pas être fusionné dans le dépôt Flower, et ce, afin que la base de code reste cohérente et facile à comprendre.

Pour ce faire, nous avons écrit quelques scripts que tu peux exécuter :
$ ./framework/dev/format.sh # to format your code $ ./framework/dev/test.sh # to test that your code can be accepted
Changements de scène
Avant de créer un commit qui mettra à jour ton historique, tu dois spécifier à Git les fichiers qu’il doit prendre en compte.

Cela peut se faire avec :
$ git add <path_of_file_to_stage_for_commit>
Pour vérifier les fichiers qui ont été modifiés par rapport à la dernière version (dernier commit) et pour voir quels fichiers sont prêts à être commités, vous pouvez utiliser la commande git status.
Commit changes
Une fois que vous avez ajouté tous les fichiers que vous avez voulu commiter en utilisant git add, vous pouvez finalement créer votre commit avec cette commande :
$ git commit -m "<commit_message>"
Le <commit_message> est là pour expliquer aux autres ce que fait la mise à jour. Il devrait être écrit dans un style impératif et être concis. Un exemple serait git commit -m "Add images to README".
Pousser les changements vers la fourche
Une fois que nous avons validé nos modifications, nous avons effectivement mis à jour notre historique local, mais GitHub n’a aucun moyen de le savoir à moins que nous ne poussions nos modifications vers l’adresse distante de notre origine :
$ git push -u origin <branch_name>
Une fois que c’est fait, tu verras sur GitHub que ton repo forké a été mis à jour avec les modifications que tu as apportées.

Créer et fusionner une pull request (PR)¶

Créer le PR
Une fois que tu as poussé les modifications, sur la page web GitHub de ton dépôt, tu devrais voir le message suivant :

Sinon, vous pouvez toujours trouver cette option dans la page Branches.

Une fois que vous cliquez sur le bouton Compare & pull request, vous devriez voir quelque chose de similaire à cela:

En haut, tu as une explication de quelle branche sera fusionnée à quel endroit :

Dans cet exemple, tu peux voir que la demande consiste à fusionner la branche doc-fixes de mon dépôt forké à la branche main du dépôt Flower.

Le titre doit être modifié pour se conformer aux lignes directrices Format du titre PR, sinon il ne sera pas possible de fusionner la PR. Donc dans ce cas, un bon titre pourrait être docs(framework:skip) Fix typos.

La zone de saisie au milieu est là pour que tu décrives ce que fait ton PR et que tu le relies aux questions existantes. Nous avons placé des commentaires (qui ne seront pas rendus une fois le PR ouvert) pour te guider tout au long du processus.

Il est important de suivre les instructions décrites dans les commentaires.

En bas de l’écran, tu trouveras le bouton permettant d’ouvrir le PR, ce qui informera les réviseurs qu’un nouveau PR a été ouvert et qu’ils doivent le consulter pour le fusionner ou demander des modifications.

Si ton RP n’est pas encore prêt à être examiné, et que tu ne veux avertir personne, tu as la possibilité de créer un brouillon de demande de traction :
Faire de nouveaux changements
Une fois que le PR a été ouvert (en tant que brouillon ou non), tu peux toujours y pousser de nouveaux commits de la même manière qu’auparavant, en apportant des modifications à la branche associée au PR.
Révisez le PR
Une fois que le PR a été ouvert ou que le projet de PR a été marqué comme étant prêt, une révision des propriétaires de code sera automatiquement demandée :

Les propriétaires du code vont alors se pencher sur le code, poser des questions, demander des modifications ou valider le RP.

La fusion sera bloquée s’il y a des changements demandés en cours.

Pour les résoudre, il suffit de pousser les changements nécessaires vers la branche associée au PR :

Et résous la conversation :

Une fois que toutes les conversations ont été résolues, tu peux redemander un examen.
Une fois que le PR est fusionné
Si tous les tests automatiques ont réussi et que les réviseurs n’ont plus de modifications à demander, ils peuvent approuver le PR et le fusionner.

Une fois qu’elle est fusionnée, tu peux supprimer la branche sur GitHub (un bouton devrait apparaître pour le faire) et aussi la supprimer localement en faisant :
$ git switch main $ git branch -D <branch_name>
Ensuite, tu dois mettre à jour ton dépôt forké en faisant :
$ git pull upstream main # to update the local repository $ git push origin main # to push the changes to the remote repository

Exemple de première contribution¶

Problème¶

Pour notre documentation, nous avons commencé à utiliser le Diàtaxis framework.

Nos guides « Comment faire » devraient avoir des titres qui continuent la phrase « Comment faire … », par exemple, « Comment mettre à jour vers Flower 1.0 ».

La plupart de nos guides ne suivent pas encore ce nouveau format, et changer leur titre est (malheureusement) plus compliqué qu’on ne le pense.

Ceci est un problème concernant la modification du titre d’un doc de présent continu à présent simple.

Prenez l’exemple de « Sauver le progrès » que nous avons changé en « Save Progress ». Passera-t-il notre test ?

Avant : « Comment sauver progress » ❌

Après : « Comment save progress » ✅

Solution¶

C’est une petite modification, mais cela permettra de tester votre configuration end-to-end. Après avoir cloné et configuré le dépôt Flower, voici ce que vous devriez faire:

Trouvez le fichier source dans framework/docs/source
Faites les modifications dans le fichier .rst (prenez soin, les tirets sous le titre doivent être de même longueur que le titre lui-même)
Construire la documentation et check the result

Renommer le fichier¶

Tu as peut-être remarqué que le nom du fichier reflète toujours l’ancienne formulation. Si nous changeons simplement le fichier, nous brisons tous les liens existants vers celui-ci - il est très important d’éviter cela, car briser des liens peut nuire à notre classement dans les moteurs de recherche.

Voici comment changer le nom du fichier :

Changez le nom du fichier en save-progress.rst
Add a redirect rule to framework/docs/source/conf.py

Cela entraînera un redirigeant vers saving-progress.html à save-progress.html, les anciens liens continueront à fonctionner.

Applique les changements dans le fichier d’index¶

Pour que la barre latérale de navigation fonctionne correctement, il est très important d’actualiser le fichier index.rst. C’est là que nous définissons toute l’arborescence du navbar.

Trouvez et modifiez le nom du fichier dans index.rst

Ouvrez une PR¶

Commitez les modifications (les messages de commit sont toujours impératifs : « Faites quelque chose », dans ce cas « Modifiez … »)
Transmets les changements à ta fourchette
Ouvrez une PR (comme ci-dessus) avec un titre docs(framework) Update how-to guide title
Attends qu’elle soit approuvée !
Félicitations 🥳 Tu es désormais officiellement une contributrice de Flower !

Prochaines étapes¶

Une fois que tu auras fait ton premier RP, et que tu voudras contribuer davantage, ne manque pas de consulter les sites suivants :

Bonnes premières contributions, en particulier les contributions baselines.

Annexe¶

Format du titre PR¶

Nous imposons le format suivant du titre PR :

<type>(<project>) <subject>

(ou <type>(<project>:skip) <subject> pour ignorer la PR dans le changelog)

Où <type> doit être en {ci, fix, feat, docs, refactor, break}, <project> devrait être en {framework, baselines, datasets, examples, or '*' when modifying multiple projects which requires the ':skip' flag to be used}, et <subject> commence par un verbe impératif au mode conjugué.

Exemples valides :

feat(framework) Add flwr build CLI command
refactor(examples:skip) Improve quickstart-pytorch logging
ci(*:skip) Enforce PR title format

Exemples invalides :

feat(framework): Add flwr build CLI command (extra :)
feat(*) Add flwr build CLI command (drapeau skip manquant ainsi que *)
feat(skip) Add flwr build CLI command (missing <project>)
feat(framework) add flwr build CLI command (non capitalised verb)
feat(framework) Add flwr build CLI command. (point à la fin)
Add flwr build CLI command. (missing <type>(<project>))