Contribute on GitHub#
This guide is for people who want to get involved with Flower, but who are not used to contributing to GitHub projects.
If youâre familiar with how contributing on GitHub works, you can directly checkout our getting started guide for contributors.
Setting up the repository#
- Create a GitHub account and setup 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, itself, is a code hosting platform for version control and collaboration. It allows for everyone to collaborate and work from anywhere on remote repositories.
If you havenât already, you will need to create an account on GitHub.
The idea behind the generic Git and GitHub workflow boils down to this: you download code from a remote repository on GitHub, make changes locally and keep track of them using Git and then you upload your new history back to GitHub.
- Forking the Flower repository
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.You can change the name if you want, but this is not necessary as this version of Flower will be yours and will sit inside your own account (i.e., in your own list of repositories). Once created, you should see on the top left corner that you are looking at your own version of Flower.
- Cloning your forked repository
The next step is to download the forked repository on your machine to be able to make changes to it. On your forked repository page, you should first click on the
Code
button on the right, this will give you the ability to copy the HTTPS link of the repository.Once you copied the <URL>, you can open a terminal on your machine, navigate to the place you want to download the repository to and type:
$ git clone <URL>
This will create a
flower/
(or the name of your fork if you renamed it) folder in the current working directory.
- Add origin
You can then go into the repository folder:
$ cd flower
And here we will need to add an origin to our repository. The origin is the <URL> of the remote fork repository. To obtain it, we can do as previously mentioned by going to our fork repository on our GitHub account and copying the link.
Once the <URL> is copied, we can type the following command in our terminal:
$ git remote add origin <URL>
- Add upstream
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
The following diagram visually explains what we did in the previous steps:
The upstream is the GitHub remote address of the parent repository (in this case Flower), i.e. the one we eventually want to contribute to and therefore need an up-to-date history of. The origin is just the GitHub remote address of the forked repository we created, i.e. the copy (fork) in our own account.
To make sure our local version of the fork is up-to-date with the latest changes from the Flower repository, we can execute the following command:
$ git pull upstream main
Setting up the coding environment#
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!
Making changes#
Before making any changes make sure you are up-to-date with your repository:
$ git pull origin main
And with Flowerâs repository:
$ git pull upstream main
- Create a new branch
To make the history cleaner and easier to work with, it is good practice to create a new branch for each feature/project that needs to be implemented.
To do so, just run the following command inside the repositoryâs directory:
$ git switch -c <branch_name>
- Make changes
Write great code and create wonderful changes using your favorite editor!
- Test and format your code
Donât forget to test and format your code! Otherwise your code wonât be able to be merged into the Flower repository. This is done so the codebase stays consistent and easy to understand.
To do so, we have written a few scripts that you can execute:
$ ./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
- Stage changes
Before creating a commit that will update your history, you must specify to Git which files it needs to take into account.
This can be done with:
$ 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.
- 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"
.
- Push the changes to the fork
Once we have committed our changes, we have effectively updated our local history, but GitHub has no way of knowing this unless we push our changes to our originâs remote address:
$ git push -u origin <branch_name>
Once this is done, you will see on the GitHub that your forked repo was updated with the changes you have made.
Creating and merging a pull request (PR)#
- Create the PR
Once you have pushed changes, on the GitHub webpage of your repository you should see the following message:
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:At the top you have an explanation of which branch will be merged where:
In this example you can see that the request is to merge the branch
doc-fixes
from my forked repository to branchmain
from the Flower repository.The input box in the middle is there for you to describe what your PR does and to link it to existing issues. We have placed comments (that wonât be rendered once the PR is opened) to guide you through the process.
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.At the bottom you will find the button to open the PR. This will notify reviewers that a new PR has been opened and that they should look over it to merge or to request changes.
If your PR is not yet ready for review, and you donât want to notify anyone, you have the option to create a draft pull request:
- Making new changes
Once the PR has been opened (as draft or not), you can still push new commits to it the same way we did before, by making changes to the branch associated with the PR.
- Review the PR
Once the PR has been opened or once the draft PR has been marked as ready, a review from code owners will be automatically requested:
Code owners will then look into the code, ask questions, request changes or validate the PR.
Merging will be blocked if there are ongoing requested changes.
To resolve them, just push the necessary changes to the branch associated with the PR:
And resolve the conversation:
Once all the conversations have been resolved, you can re-request a review.
- Once the PR is merged
If all the automatic tests have passed and reviewers have no more changes to request, they can approve the PR and merge it.
Once it is merged, you can delete the branch on GitHub (a button should appear to do so) and also delete it locally by doing:
$ git switch main $ git branch -D <branch_name>
Then you should update your forked repository by doing:
$ git pull upstream main # to update the local repository $ git push origin main # to push the changes to the remote repository
Example of first contribution#
Problem#
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â.
Most of our guides do not follow this new format yet, and changing their title is (unfortunately) more involved than one might think.
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
Rename file#
You might have noticed that the file name still reflects the old wording. If we just change the file, then we break all existing links to it - it is very important to avoid that, breaking links can harm our search engine ranking.
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.
Apply changes in the index file#
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 âŠâ)
Push the changes to your fork
Open a PR (as shown above)
Wait for it to be approved!
Congrats! đ„ł Youâre now officially a Flower contributor!
How to write a good PR title#
A well-crafted PR title helps team members quickly understand the purpose and scope of the changes being proposed. Hereâs a guide to help you write a good GitHub PR title:
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.
Letâs start with a few examples for titles that should be avoided because they do not provide meaningful information:
Implement Algorithm
Database
Add my_new_file.py to codebase
Improve code in module
Change SomeModule
Here are a few positive examples which provide helpful information without repeating how they do it, as that is already visible in the âFiles changedâ section of the 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 changesAdd new amazing library which will be used to improve the simulation engine
Next steps#
Once you have made your first PR, and want to contribute more, be sure to check out the following :
Good first contributions, where you should particularly look into the
baselines
contributions.
Appendix#
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.