成为贡献者#

先决条件#

Python 3.8 or above
Poetry 1.3 或更高版本
(可选） pyenv
(可选） 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.

开发者机器设置#

Preliminarities#

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 [email protected]:adap/flower.git
$ cd flower

Let's create the Python environment for all-things Flower. If you wish to use pyenv, we provide two convenience scripts that you can use. If you prefer using something else than pyenv, create a new environment, activate and skip to the last point where all packages are installed.

If you don't have pyenv installed, the following script that will install it, set it up, and create the virtual environment (with Python 3.8.17 by default):
```
$ ./dev/setup-defaults.sh <version> # once completed, run the bootstrap script
```
If you already have pyenv installed (along with the pyenv-virtualenv plugin), you can use the following convenience script (with Python 3.8.17 by default):
```
$ ./dev/venv-create.sh <version> # once completed, run the `bootstrap.sh` script
```

3. Install the Flower package in development mode (think pip install -e) along with all necessary dependencies:

(flower-<version>) $ ./dev/bootstrap.sh

便捷脚本#

Flower 软件仓库包含大量便捷脚本，可使重复性开发任务更轻松、更不易出错。完整列表请参见 /dev 子目录。以下是最重要的脚本：

创建/删除虚拟环境#

$ ./dev/venv-create.sh <version> # Default is 3.8.17
$ ./dev/venv-delete.sh <version> # Default is 3.8.17

编译 ProtoBuf 定义#

$ python -m flwr_tool.protoc

自动格式化代码#

$ ./dev/format.sh

运行分类器和测试#

$ ./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: ./dev/format.sh and ./dev/test.sh scripts.

There are multiple ways developers can use this:

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"
```
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.

在本地运行 Github 操作 (CI)#

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

Flower 默认工作流程将通过在下面设置所需的 Docker 机器来运行。

版本发布#

Flower 使用 Poetry 创建发布版本。必要的命令封装在一个简单的脚本中：：

$ ./dev/build.sh

生成的 .whl 和 .tar.gz 版本将存储在 /dist 子目录中。

构建文档#

Flower 的文档使用 Sphinx。目前还没有很方便的脚本来重新构建文档，不过这很容易：：

$ cd doc
$ make html

这将在 doc/build/html 中生成 HTML 文档。

Note that, in order to build the documentation locally (with poetry run make html, like described below), Pandoc needs to be installed on the system.