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>

    Pour vérifier quels fichiers ont été modifiés par rapport à la dernière version (last commit) et pour voir quels fichiers sont mis à disposition pour le commit, tu peux utiliser la commande git status.

  5. Commit changes

    Une fois que tu as ajouté tous les fichiers que tu voulais livrer à l’aide de git add, tu peux enfin créer ta livraison à l’aide de cette commande :

    $ git commit -m "<commit_message>"

    Le commit_message est là pour expliquer aux autres ce que fait le commit. Il doit être écrit dans un style impératif et être concis. Un exemple serait git commit -m "Ajouter des images au 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.

    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. For instance, in order to not break how our changelog system works, you should read the information above the Changelog entry section carefully. You can also checkout some examples and details in the Changelog entry appendix.

    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 doc/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 doc/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

  • Ouvre un RP (comme indiqué ci-dessus)

  • Attends qu’elle soit approuvée !

  • Félicitations 🥳 Tu es désormais officiellement une contributrice de Flower !

Comment écrire un bon titre de PR#

Un titre de PR bien choisi permet aux autres développeurs de rapidement comprendre l’intérêt et le scope des changements proposés. Voici un guide pour vous aider à écrire des bons titres de PR :

1. Be Clear and Concise: Provide a clear summary of the changes in a concise manner. 1. Use Actionable Verbs: Start with verbs like « Add, » « Update, » or « Fix » to indicate the purpose. 1. Include Relevant Information: Mention the affected feature or module for context. 1. Keep it Short: Avoid lengthy titles for easy readability. 1. Use Proper Capitalization and Punctuation: Follow grammar rules for clarity.

Commençons par quelques exemples de titres qui devraient être évités parce qu’ils ne fournissent pas d’information significative :

  • Implement Algorithm

  • Database

  • Add my_new_file.py to codebase

  • Improve code in module

  • Change SomeModule

Voici quelques bons exemples qui fournissent de l’information utile sans répéter comment ils le font, comme cela est déjà visible dans la section « Files changed » de la PR :

  • Update docs banner to mention Flower Summit 2023

  • Remove unnecessary XGBoost dependency

  • Remove redundant attributes in strategies subclassing FedAvg

  • Add CI job to deploy the staging system when the main branch changes

  • Add new amazing library which will be used to improve the simulation engine

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#

Changelog entry#

When opening a new PR, inside its description, there should be a Changelog entry header.

Above this header you should see the following comment that explains how to write your changelog entry:

Inside the following “Changelog entry” section, you should put the description of your changes that will be added to the changelog alongside your PR title.

If the section is completely empty (without any token) or non-existent, the changelog will just contain the title of the PR for the changelog entry, without any description.

If the section contains some text other than tokens, it will use it to add a description to the change.

If the section contains one of the following tokens it will ignore any other text and put the PR under the corresponding section of the changelog:

<general> is for classifying a PR as a general improvement.

<skip> is to not add the PR to the changelog

<baselines> is to add a general baselines change to the PR

<examples> is to add a general examples change to the PR

<sdk> is to add a general sdk change to the PR

<simulations> is to add a general simulations change to the PR

Note that only one token should be used.

Its content must have a specific format. We will break down what each possibility does:

  • If the ### Changelog entry section contains nothing or doesn’t exist, the following text will be added to the changelog:

    - **PR TITLE** ([#PR_NUMBER](https://github.com/adap/flower/pull/PR_NUMBER))

  • If the ### Changelog entry section contains a description (and no token), the following text will be added to the changelog:

    - **PR TITLE** ([#PR_NUMBER](https://github.com/adap/flower/pull/PR_NUMBER))

    DESCRIPTION FROM THE CHANGELOG ENTRY

  • If the ### Changelog entry section contains <skip>, nothing will change in the changelog.

  • If the ### Changelog entry section contains <general>, the following text will be added to the changelog:

    - **General improvements** ([#PR_NUMBER](https://github.com/adap/flower/pull/PR_NUMBER))

  • If the ### Changelog entry section contains <baselines>, the following text will be added to the changelog:

    - **General updates to Flower Baselines** ([#PR_NUMBER](https://github.com/adap/flower/pull/PR_NUMBER))

  • If the ### Changelog entry section contains <examples>, the following text will be added to the changelog:

    - **General updates to Flower Examples** ([#PR_NUMBER](https://github.com/adap/flower/pull/PR_NUMBER))

  • If the ### Changelog entry section contains <sdk>, the following text will be added to the changelog:

    - **General updates to Flower SDKs** ([#PR_NUMBER](https://github.com/adap/flower/pull/PR_NUMBER))

  • If the ### Changelog entry section contains <simulations>, the following text will be added to the changelog:

    - **General updates to Flower Simulations** ([#PR_NUMBER](https://github.com/adap/flower/pull/PR_NUMBER))

Note that only one token must be provided, otherwise, only the first action (in the order listed above), will be performed.