成为贡献者

先决条件

Flower uses pyproject.toml to manage dependencies and configure development tools (the ones which support it). uv is used for dependency management, build, and publishing workflows.

开发者机器设置

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:flwrlabs/flower.git
$ cd flower

  2. Install uv by following the uv installation instructions.

  3. Bootstrap the framework development environment:

    $ ./dev/bootstrap.sh

    The bootstrap script creates framework/.venv using the Python version pinned by the repository. Pass a Python version as the first argument to use a different one:

    $ ./dev/bootstrap.sh 3.11.14

便捷脚本

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:

编译 ProtoBuf 定义

$ ./framework/dev/protoc.sh

自动格式化代码

$ ./framework/dev/format.sh

运行分类器和测试

$ ./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.

在本地运行 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 uses uv 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.

构建文档

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.