Skip to main content

为 Blaflow 做贡献

本指南旨在帮助您开始为 Blaflow 做贡献。 作为一个在快速发展的领域中的开源项目，Blaflow 欢迎各种形式的贡献，无论是新功能、改进基础设施还是更好的文档。

要向此项目贡献代码或文档，请遵循 fork 和 pull request 工作流程。

贡献代码​

使用 uv 和 Node.js 在本地开发 Blaflow。

前提条件​

准备开发环境​

  1. 创建开发钩子。

_10
make init

此命令通过安装后端和前端依赖、构建前端静态文件并初始化项目来设置开发环境。它运行 make install_backend、make install_frontend、make build_frontend，最后运行 uv run blaflow run 来启动应用程序。

  1. 在推送到仓库之前运行 make lint、make format 和 make unit_tests。

调试​

仓库包含一个 .vscode/launch.json 文件，用于在 VSCode 中调试后端，这比使用 Docker Compose 调试更快。要在 VSCode 中使用 launch.json 文件调试 Blaflow：

  1. 在 VSCode 中打开 Blaflow。
  2. 按 Ctrl+Shift+D（Windows）或 Cmd+Shift+D（Mac）打开运行和调试视图。
  3. 从 运行和调试 下拉菜单中选择调试配置。
  4. 点击绿色的 播放 按钮或按 F5 开始调试。

使用 launch.json 可以直接从 VSCode 快速调试应用程序的不同部分，如后端、前端或 CLI。

在本地运行 Blaflow​

使用 make init 设置环境后，您可以分别运行 Blaflow 的后端和前端进行开发。 Blaflow 建议使用 venv 或 conda 等虚拟环境来隔离依赖项。

在开始之前，确保您已安装 uv 和 Node.js。

  1. 在仓库根目录中，安装依赖项并启动后端开发服务器：

_10
make backend

  1. 安装依赖项并启动前端：

_10
make frontend

这种方法允许您独立处理后端和前端，并支持热重载以加快开发速度。

贡献文档​

文档使用 Docusaurus 构建，并使用 Markdown 编写。

前提条件​

克隆 Blaflow 仓库​

  1. 导航到 Blaflow GitHub 仓库，然后点击 Fork。

  2. 在本地机器上为您的本地仓库添加新的远程仓库：


_10
git remote add fork https://github.com/<your_git_username>/blaflow.git

  1. 要在本地运行文档，请运行以下命令：

_10
cd docs
_10
yarn install
_10
yarn start

文档将在 localhost:3000 上可用，所有文件都位于 docs/docs 文件夹中。

提交 pull request​

一旦您编写并手动测试了您的更改（使用 make lint 和 make unit_tests），就可以提交 pull request 将您的更改发送到主 Blaflow 仓库。

  1. 打开一个新的 GitHub pull request，将您的补丁提交到 main 分支。
  2. 确保 PR 标题遵循语义化提交约定。例如，新功能是 feat: add new feature，修复是 fix: correct issue with X。
  3. Blaflow 维护者将审查您的 pull request。感谢您的贡献！

关于 pull request 标题的一些额外指导：

  • 确保 pull request 描述清楚地描述了问题和解决方案。如果 PR 修复了一个问题，请在 PR 描述中包含指向已修复问题的链接，使用 Fixes #1234。
  • Pull request 标题会出现在 Blaflow 的发布说明中，因此它们应该尽可能明确地解释 PR 的功能。
  • Pull request 应该只修复一件事，并应该包含对正在修复的内容的良好描述。

有关更多信息，请参阅 Python 开发者指南。