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.

If you’re familiar with how contributing on GitHub works, you can directly checkout our getting started guide for contributors.

Mise en place du référentiel

  1. Créer un compte GitHub et configurer Git

    Git is a distributed version control tool. This allows for an entire codebase’s history to be stored and every developer’s machine. It is a software that will need to be installed on your local machine, you can follow this guide to set it up.

    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.

  2. Fourche le dépôt de Flower

    A fork is a personal copy of a GitHub repository. To create one for Flower, you must navigate to https://github.com/adap/flower (while connected to your GitHub account) and click the Fork button situated on the top right of the page.

    _images/fork_button.png

    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.

    _images/fork_link.png
  3. 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.

    _images/cloning_fork.png

    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>

    This will create a flower/ (or the name of your fork if you renamed it) folder in the current working directory.

  4. 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.

    _images/cloning_fork.png

    Une fois que le <URL> est copié, nous pouvons taper la commande suivante dans notre terminal :

    $ git remote add origin <URL>
  5. Ajouter en amont

    Now we will add an upstream address to our repository. Still in the same directory, we must run the following command:

    $ git remote add upstream https://github.com/adap/flower.git

    Le schéma suivant explique visuellement ce que nous avons fait dans les étapes précédentes :

    _images/github_schema.png

    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

This can be achieved by following this getting started guide for contributors (note that you won’t need to clone the repository). Once you are able to write code and test it, you can finally start making changes!

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
  1. 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>
  2. Apporter des modifications

    Écris du bon code et crée de merveilleuses modifications à l’aide de ton éditeur préféré !

  3. 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 :

    $ ./dev/format.sh # to format your code
$ ./dev/test.sh # to test that your code can be accepted
$ ./baselines/dev/format.sh # same as above but for code added to baselines
$ ./baselines/dev/test.sh # same as above but for code added to baselines
  4. 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>

    To check which files have been modified compared to the last version (last commit) and to see which files are staged for commit, you can use the git status command.

  5. Commit changes

    Once you have added all the files you wanted to commit using git add, you can finally create your commit using this command:

    $ git commit -m "<commit_message>"

    The <commit_message> is there to explain to others what the commit does. It should be written in an imperative style and be concise. An example would be git commit -m "Add images to README".

  6. 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)

  1. 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 :

    _images/compare_and_pr.png

    Otherwise you can always find this option in the Branches page.

    Once you click the Compare & pull request button, you should see something similar to this:

    _images/creating_pr.png

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

    _images/merging_branch.png

    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.

    The title should be changed to adhere to the PR title format guidelines, otherwise it won’t be possible to merge the PR. So in this case, a correct title might be 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.

    It is important to follow the instructions described in comments.

    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 :

    _images/draft_pr.png
  2. 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.

  3. Review the 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 :

    _images/opened_pr.png

    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.

    _images/changes_requested.png

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

    _images/make_changes.png

    Et résous la conversation :

    _images/resolve_conv.png

    Une fois que toutes les conversations ont été résolues, tu peux redemander un examen.

  4. 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.

    _images/merging_pr.png

    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

For our documentation, we’ve started to use the Diàtaxis framework.

Our « How to » guides should have titles that continue the sentence « How to … », for example, « How to upgrade to 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.

This issue is about changing the title of a doc from present continuous to present simple.

Let’s take the example of « Saving Progress » which we changed to « Save Progress ». Does this pass our check?

Before: « How to saving progress » ❌

After: « How to save progress » ✅

Solution

This is a tiny change, but it’ll allow us to test your end-to-end setup. After cloning and setting up the Flower repo, here’s what you should do:

  • Find the source file in framework/docs/source

  • Make the change in the .rst file (beware, the dashes under the title should be the same length as the title itself)

  • Build the docs and 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.

Here’s how to change the file name:

  • Change the file name to save-progress.rst

  • Add a redirect rule to framework/docs/source/conf.py

This will cause a redirect from saving-progress.html to save-progress.html, old links will continue to work.

Applique les changements dans le fichier d’index

For the lateral navigation bar to work properly, it is very important to update the index.rst file as well. This is where we define the whole arborescence of the navbar.

  • Find and modify the file name in index.rst

Open PR

  • Commit the changes (commit messages are always imperative: « Do something », in this case « Change … »)

  • Transmets les changements à ta fourchette

  • Open a PR (as shown above) with title 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 :

Annexe

PR title format

We enforce the following PR title format:

<type>(<project>) <subject>

(or <type>(<project>:skip) <subject> to ignore the PR in the changelog)

Where <type> needs to be in {ci, fix, feat, docs, refactor, break}, <project> should be in {framework, baselines, datasets, examples, or '*' when modifying multiple projects which requires the ':skip' flag to be used}, and <subject> starts with a capitalised verb in the imperative mood.

Valid examples:

  • feat(framework) Add flwr build CLI command

  • refactor(examples:skip) Improve quickstart-pytorch logging

  • ci(*:skip) Enforce PR title format

Invalid examples:

  • feat(framework): Add flwr build CLI command (extra :)

  • feat(*) Add flwr build CLI command (missing skip flag along with *)

  • 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. (dot at the end)

  • Add flwr build CLI command. (missing <type>(<project>))