Get started as a contributor ============================ Prerequisites ------------- - `Python 3.9 `_ or above - `Poetry 1.3 `_ or above - (Optional) `pyenv `_ - (Optional) `pyenv-virtualenv `_ Flower uses ``pyproject.toml`` to manage dependencies and configure development tools (the ones which support it). Poetry is a build tool which supports `PEP 517 `_. Developer Machine Setup ----------------------- Preliminaries ~~~~~~~~~~~~~ Some system-wide dependencies are needed. For macOS +++++++++ - Install `homebrew `_. Don't forget the post-installation actions to add `brew` to your PATH. - Install `xz` (to install different Python versions) and `pandoc` to build the docs: :: $ brew install xz pandoc For Ubuntu ++++++++++ Ensure you system (Ubuntu 22.04+) is up-to-date, and you have all necessary packages: :: $ apt update $ apt install build-essential zlib1g-dev libssl-dev libsqlite3-dev \ libreadline-dev libbz2-dev libffi-dev liblzma-dev pandoc Create Flower Dev Environment ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 1. Clone the `Flower repository `_ from GitHub: :: $ git clone git@github.com:adap/flower.git $ cd flower 2. Create and activate a Python virtual environment for development. See `Set up a virtual env `_ for detailed instructions. One way to do this is by using `pyenv `_ and `pyenv-virtualenv `_. You can also optionally install a specific Python version using pyenv if you haven't already installed your desired version: :: $ pyenv install $ pyenv virtualenv $ pyenv activate 3. Install Poetry, which is used to manage dependencies and development workflows: :: (your-env-name) $ pip install poetry==2.1.3 4. Navigate to the ``framework`` directory and install the Flower project in development mode, including all optional dependencies: :: (your-env-name) $ cd framework (your-env-name) $ python -m poetry install --all-extras Convenience Scripts ------------------- The Flower repository contains a number of convenience scripts to make recurring development tasks easier and less error-prone. See the ``/dev`` subdirectory for a full list. The following scripts are amongst the most important ones: Compile ProtoBuf Definitions ~~~~~~~~~~~~~~~~~~~~~~~~~~~~ :: $ python -m flwr_tool.protoc Auto-Format Code ~~~~~~~~~~~~~~~~ :: $ ./framework/dev/format.sh Run Linters and Tests ~~~~~~~~~~~~~~~~~~~~~ :: $ ./framework/dev/test.sh Add a pre-commit hook ~~~~~~~~~~~~~~~~~~~~~ Developers may integrate a pre-commit hook into their workflow utilizing the `pre-commit `_ library. The pre-commit hook is configured to execute two primary operations: ``./framework/dev/format.sh`` and ``./framework/dev/test.sh`` scripts. There are multiple ways developers can use this: 1. Install the pre-commit hook to your local git directory by simply running: :: $ pre-commit install - Each ``git commit`` will trigger the execution of formatting and linting/test scripts. - If in a hurry, bypass the hook using ``--no-verify`` with the ``git commit`` command. :: $ git commit --no-verify -m "Add new feature" 2. For developers who prefer not to install the hook permanently, it is possible to execute a one-time check prior to committing changes by using the following command: :: $ pre-commit run --all-files This executes the formatting and linting checks/tests on all the files without modifying the default behavior of ``git commit``. Run Github Actions (CI) locally ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ Developers could run the full set of Github Actions workflows under their local environment by using `Act `_. Please refer to the installation instructions under the linked repository and run the next command under Flower main cloned repository folder: :: $ act The Flower default workflow would run by setting up the required Docker machines underneath. Build Release ------------- Flower uses Poetry to build releases. The necessary command is wrapped in a simple script: :: $ ./framework/dev/build.sh The resulting ``.whl`` and ``.tar.gz`` releases will be stored in the ``./framework/dist`` subdirectory. Build Documentation ------------------- Flower's documentation uses `Sphinx `_. To build the documentation locally, run the following script: :: $ ./framework/dev/build-docs.sh This will generate HTML documentation in ``./framework/doc/build/html``. Note that, in order to build the documentation locally, `Pandoc `_ needs to be installed on the system.