Crawl4AI 贡献指南与发布流程：GitFlow 分支策略、双周发布机制与源码级版本管理解析

本文以 Crawl4AI 仓库根目录的 CONTRIBUTING.md 为主体，完整梳理其 GitFlow 风格的分支策略（main / develop / next / release/vX.Y.Z）、贡献者工作流与双周发布流程，并结合 crawl4ai/__version__.py、pyproject.toml、Dockerfile、mkdocs.yml、cliff.toml 等真实源码与配置，讲解版本号在构建、文档站点与 Docker 镜像之间的一致性维护机制。读完后你既能按规范向 develop 分支提交合格的 Pull Request，也能理解一个合并后的变更是如何随双周节奏进入正式版本并同步到 PyPI 与 Docker Hub 的。

核心分支模型：四条分支各司其职

Crawl4AI 采用 GitFlow 风格的分支工作流，以保证发布的可预测性与质量。仓库维护 main、develop、next 三类长期分支，外加临时性的 release/vX.Y.Z 发布分支：

• main：稳定分支，包含生产可用的代码，始终与最新已发布版本保持一致，并按发布打 tag。禁止直接向该分支提交 PR。
• develop：主集成分支，承载所有进行中的开发。所有社区贡献（Bug 修复、小功能、文档更新）都合并到这里，PR 一律以 develop 为目标分支。
• next：预留给主要维护者（Unclecode）实验大功能、重构或前沿改动。待成熟后再合并入 develop，从而隔离实验性改动，避免干扰贡献者的工作。
• release/vX.Y.Z：从 develop 切出的临时分支，用于最终发布准备（版本号提升、演示脚本、发布说明等），生命周期短，发布完成后即删除。

从源码结构可以印证这套流程中的关键落点。稳定版本号集中定义在 crawl4ai/version.py：

# crawl4ai/__version__.py
# This is the version that will be used for stable releases
__version__ = "0.9.0"

# For nightly builds, this gets set during build process
__nightly_version__ = None

其中 __nightly_version__ 留空、构建时注入的注释，正好对应 CONTRIBUTING.md 中提到的预发布（pre-release）测试机制；而发布时"Version bump in code（e.g., __version__.py）"这一步指的就是修改该文件。

贡献者工作流：从 Fork 到 PR 的六步

CONTRIBUTING.md 鼓励所有类型的贡献：Bug 修复、新功能、文档改进、测试，乃至 Docker 相关的增强。标准流程如下：

第 1 步：Fork 仓库

在自己的 GitHub 账户下创建仓库的 Fork。

第 2 步：基于 develop 创建分支

git checkout develop
git checkout -b feature/your-feature-name   # 或 bugfix/your-bugfix-name

第 3 步：实施改动

• 实现功能或修复 Bug；

• 若更新文档（如 README.md、mkdocs.yml、docs/blog/ 等），注意保持版本引用的一致性（例如必要时把 mkdocs.yml 中的 site_name 更新为对应版本）。当前仓库中该行实际为 site_name: Crawl4AI Documentation (v0.9.x)，与 __version__.py 中的 0.9.0 相互对应；

• 若涉及 Docker 相关改动（如 Dockerfile、docker-compose.yml、docs/md_v2/core/docker-deployment.md），需在本地构建测试，并在 PR 描述中附上构建说明。Dockerfile 中版本同样以构建参数形式声明：

  # C4ai version
  ARG C4AI_VER=0.9.0
  LABEL c4ai.version=$C4AI_VER
  

  发布流程中的"Dockerfile（version arg）"即指同步这里的 C4AI_VER；

• 视情况添加测试，并运行 pytest 验证；

• 遵循代码风格规范（文档建议使用 black 格式化）。

第 4 步：提交与推送

• 使用描述性提交信息，例如 "Fix: Resolve issue with async crawling"；
• 推送到自己的 Fork：git push origin feature/your-feature-name。

仓库根目录的 cliff.toml 配置了 Conventional Commits 的解析规则，提交信息前缀会直接决定 CHANGELOG.md 中的分组：

[git]
conventional_commits = true
filter_unconventional = true
commit_parsers = [
    { message = "^feat", group = "Added"},
    { message = "^fix", group = "Fixed"},
    { message = "^doc", group = "Documentation"},
    { message = "^perf", group = "Performance"},
    { message = "^refactor", group = "Changed"},
    { message = "^style", group = "Changed"},
    { message = "^test", group = "Testing"},
    { message = "^chore\\(release\\): prepare for", skip = true},
    { message = "^chore", group = "Miscellaneous Tasks"},
]

因此 feat:、fix: 等前缀不只是为了规范，它们会驱动 changelog 自动生成时的 "Added / Fixed / Documentation / Performance" 分组；chore(release): prepare for 类提交则被显式跳过。

第 5 步：提交 Pull Request

• 目标分支为 develop；
• 提供清晰描述：改动做什么、关联哪个 issue，必要时附截图或代码示例；
• 若改动影响文档或 Docker，说明其与当前版本的对齐方式（例如 "Updates Docker docs for v0.7.0 compatibility"）；
• 审查通过后，PR 将合并入 develop。

若 PR 涉及破坏性变更（breaking changes），必须在描述中附带迁移指南（migration guide）。

第 6 步：大改动先讨论

对于重大功能或实验性想法，建议先开 issue 与项目方向对齐，再动手实现。

主要维护者的工作流（参考说明）

• 主要维护者（Unclecode）使用 next 分支做隔离的实验性开发；
• next 中的功能会定期通过 rebase + merge 的方式同步进 develop；
• 这种隔离设计确保贡献者的分支不会被进行中的大改动打断——你始终基于 develop 工作即可。

发布流程：双周节奏下的完整链路

Crawl4AI 以大约两周一次的节奏发布版本，目标是持续、稳定地交付改进。贡献者合并进 develop 的改动，除非特别说明，都会进入下一个版本。发布过程的高层链路如下：

1. 准备阶段（Preparation）

从 develop 切出临时的 release/vX.Y.Z 分支；将 next 中已就绪的功能合并进来。

2. 最终更新（Final Updates）

• 代码版本号提升：修改 crawl4ai/__version__.py 中的 __version__；
• 示例脚本：在 examples/ 中创建演示脚本，展示新特性（仓库 docs/examples/ 下有大量真实示例可参照，如 quickstart.py、research_assistant.py）；
• 发布说明：在 docs/blog/ 撰写，采用维护者第一人称口吻，包含代码示例、影响面说明和必要的迁移指南。现有如 docs/blog/release-v0.8.0.md、docs/blog/release-v0.8.5.md 等即为历次发布记录的实例；
• 文档同步：更新 README.md（亮点与版本引用）、mkdocs.yml（带版本的 site_name）、docs/md_v2/blog/index.md（新增该次发布的索引条目，该文件实际按 "Latest Release / Recent Releases" 组织，最新一条指向 docs/blog/ 下的发布说明），并把发布说明复制到 docs/md_v2/blog/releases/；
• Docker 同步：更新 Dockerfile（version arg，即 C4AI_VER）、docker-compose.yml、deploy/docker/README.md 与 docs/md_v2/core/docker-deployment.md，构建并测试发布候选镜像（如 X.Y.Z-r1）。

3. 测试与合并（Testing and Merge）

跑全量测试，提交变更，将 release/vX.Y.Z 合并到 main 并打 tag。

4. 对外发布（Publication）

在 GitHub 发布带说明的 tagged release、发布到 PyPI、推送 Docker 镜像（latest 标签在稳定版测试通过后更新）。

5. 回同步（Sync）

把发布结果反向合并回 develop，并重置 next 分支，为下一个周期做准备。

版本号的动态引用机制

发布流程中"版本号提升"这一步之所以只需改一处源码文件，是因为构建系统将其动态引用。pyproject.toml 中声明：

[project]
name = "Crawl4AI"
dynamic = ["version"]
requires-python = ">=3.10"

[tool.setuptools.dynamic]
version = {attr = "crawl4ai.__version__.__version__"}

[tool.setuptools.dynamic] 从 crawl4ai.__version__ 模块读取 __version__ 属性作为包版本，即 PyPI 包版本、源码与发布 tag 三方由同一文件保持一致。运行时也有类似的一致性检查逻辑：crawl4ai/utils.py 与 crawl4ai/legacy/version_manager.py 都会读写版本文件并与已安装版本比较，用于提示用户升级。

语义化版本规则

项目遵循 Semantic Versioning：

• MAJOR：破坏性变更；
• MINOR：新功能；
• PATCH：修复；
• 预发布版本（如 -rc1）可用于测试。

changelog 同样遵循该约定：CHANGELOG.md 顶部声明格式基于 Keep a Changelog 并遵循语义化版本，条目按版本倒序排列（当前最新为 0.9.0）。CONTRIBUTING.md 也提醒：如果你的贡献涉及 Docker 测试或文档，可能正属于发布准备环节——欢迎在 PR 中主动提出文档更新建议。

这套流程带来的收益

CONTRIBUTING.md 从四个维度总结了这种工作流的价值：

• 稳定性（Stability）：main 对用户始终可靠；
• 协作性（Collaboration）：PR 目标分支固定为 develop，贡献路径清晰；
• 隔离性（Isolation）：next 中的实验性工作不会阻塞团队整体进度；
• 用户导向（User-Focused）：每个版本都附带演示脚本、详细发布说明和同步更新的文档与 Docker 资产，降低采用成本；
• 可预期性（Predictability）：双周节奏保持项目持续活跃。

贡献者提交前检查清单

CONTRIBUTING.md 给出的 PR 前 Checklist 原样保留如下：

• [ ] 基于 develop 且目标分支为 develop；
• [ ] 测试通过（pytest）；
• [ ] 必要时更新文档（如 mkdocs.yml 中的版本引用、Docker 相关文件）；
• [ ] 破坏性变更必须附迁移指南；
• [ ] PR 标题与描述具有描述性。

常见问题处理

• 合并冲突（Merge Conflicts）：提 PR 前先将分支 rebase 到最新的 develop；
• Docker 构建（Docker Builds）：若改动了 Dockerfile，请在本地测试多架构（amd64 / arm64）。Dockerfile 中确实按 TARGETARCH 区分了 amd64 与 arm64 的安装分支，印证了多架构支持；
• 版本一致性（Version Consistency）：确保所有版本引用都符合语义化版本规则——实践中至少涉及 crawl4ai/__version__.py、mkdocs.yml 的 site_name、Dockerfile 的 C4AI_VER、docs/blog/index.md 与 docs/md_v2/blog/ 下的发布说明索引这几处。

沟通渠道

• 讨论或 Bug 一律通过 issue 发起；
• 项目 README 中提供了 Discord 社区入口，可用于实时交流；
• 每次发布后，公告会同步到 GitHub、Discord 与社交媒体渠道。

小结

Crawl4AI 的贡献体系本质上是一个"贡献者只面向 develop、发布由 release/vX.Y.Z 临时分支统一收口"的双周节奏流水线：分支职责清晰（main 稳定、develop 集成、next 实验）、版本号的单一事实来源是 crawl4ai/__version__.py 并经 pyproject.toml 动态引用、changelog 由 Conventional Commits 规则驱动生成、发布说明与文档索引（mkdocs.yml、docs/blog/、docs/md_v2/blog/releases/）、Docker 资产（Dockerfile、docker-compose.yml）在同一发布窗口内同步更新。理解并遵循这一链路，你的 PR 才能在合并后平滑地进入下一次双周发布。