Crawl4AI 贡献实战：GitFlow 风格分支策略、PR 流程与双周发布管线

Crawl4AI 采用一套 GitFlow 风格的协作流程来管理一个包含浏览器自动化、深度爬取与 Docker API 服务的多模块项目，其贡献指南 CONTRIBUTING.md 定义了四条核心分支的职责边界、从 Fork 到 PR 的六步贡献流程，以及以语义化版本为基础的双周发布管线。读懂本文后，你将掌握如何基于 develop 分支创建规范分支、按仓库要求组织提交信息与测试，并理解版本 bump、Docker 镜像构建与发布说明在仓库中对应哪些具体文件。

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

Crawl4AI 的分支模型分为稳定分支、集成分支、实验分支与临时发布分支四类，这是理解整个贡献流程的前提。

• main：稳定分支，只包含生产可用代码，且始终与最新发布的版本完全一致，用于打 release 标签。贡献者不应直接向该分支提交 PR。
• develop：主集成分支。所有贡献——bug 修复、小型功能、文档更新——都合并到这里，因此所有 PR 的目标分支都是 develop。
• next：由主维护者（Unclecode）保留，用于实验重大功能、重构或前沿改动，成熟后再合并回 develop。
• release/vX.Y.Z：从 develop 切出的临时发布分支，用于版本 bump、演示脚本、发布说明等收尾工作，发布完成后即删除。

这种隔离设计带来三个直接收益（原文档的 “Benefits” 部分）：

• 稳定性：main 对用户始终可靠，随时可安装使用；
• 协作简单：PR 目标分支固定为 develop，新贡献者不需要纠结该提给谁；
• 隔离性：next 上的实验性改动不会阻塞团队其他进展；
• 以用户为中心：每次发布附带演示脚本、详细发布说明与更新后的文档和 Docker 产物，降低采用成本；
• 可预期性：约每两周一次的发布节奏保持项目活跃。

主维护者的工作流同样值得了解：主维护者在 next 分支上做隔离实验，再把 next 周期性 rebase 后合并进 develop 保持同步——这正是贡献者的 PR 不会被打断的原因。

贡献者工作流：六步提交代码

原文档将贡献流程定义为六个步骤，以下完整保留并补充仓库侧的执行细节。

第 1–2 步：Fork 仓库并基于 develop 建分支

在自己的 GitHub fork 中创建分支，且必须以 develop 为基础：

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

分支命名遵循 feature/ 或 bugfix/ 前缀约定，让评审者一眼识别 PR 类型。

第 3 步：实施改动（含文档与 Docker 专项要求）

改动时的仓库特定约束有四点：

1. 实现功能或修复：核心代码位于 crawl4ai/ 包内，构建元数据在 pyproject.toml 中定义，可选依赖组包括 pdf、torch、transformer、cosine、sync、all，新增依赖时应评估归属哪一组。
2. 文档改动：若更新 README.md、mkdocs.yml 或 docs/blog/ 下的内容，需保证版本引用一致——例如 mkdocs.yml 第 1 行的 site_name 当前为 Crawl4AI Documentation (v0.9.x)，文档站导航的 Community 板块直接挂载了 CONTRIBUTING.md。
3. Docker 改动：涉及 Dockerfile、docker-compose.yml 或 deploy/docker/ 目录时，必须本地测试，并在 PR 描述中附上构建说明。以当前仓库为例，Dockerfile 顶部通过 ARG C4AI_VER=0.9.0 注入版本并写入 LABEL c4ai.version，镜像基于 python:3.12-slim-bookworm，同时通过 ARG TARGETARCH 支持 amd64/arm64 多架构构建——这正是下文 “Common Issues” 中要求本地测试多架构的原因。
4. 测试与代码风格：如适用则补充测试并运行 pytest 验证（仓库测试代码集中在 tests/ 目录，覆盖 async、browser、proxy、docker、regression 等场景）；代码格式统一使用 black。

第 4–5 步：提交、推送与发起 PR

• 提交信息要有描述性，例如 "Fix: Resolve issue with async crawling"；
• 推送到 fork：git push origin feature/your-feature-name；
• 发起 PR 时目标为 develop，描述需回答“它做什么”，关联 issue，必要时附截图或代码示例；
• 若改动涉及文档或 Docker，需说明与目标版本的对齐关系（如 “Updates Docker docs for v0.7.0 compatibility”）。

提交信息约定不是形式要求：仓库根目录的 cliff.toml 配置了 git-cliff 自动生成 CHANGELOG.md，其中 conventional_commits = true 且 filter_unconventional = true，即不符合 conventional commits 格式的提交会被直接过滤出 Changelog。其提交类型到 Changelog 分组的映射为：

提交前缀	Changelog 分组
feat	Added
fix	Fixed
doc	Documentation
perf	Performance
refactor	Changed
style	Changed
test	Testing
chore	Miscellaneous Tasks
chore(release): prepare for	（跳过）

因此，写 feat:、fix: 等前缀既是对协作者的说明，也决定了你的改动是否会出现在最终发布的 Changelog 里。

第 6 步：重大改动先讨论

大型功能或实验性想法应先在 issue 中提出，与项目方向对齐后再动手。若 PR 包含破坏性变更，必须在描述中附上迁移指南。仓库中现成的范例包括 docs/migration/v0.8.0-upgrade-guide.md 与 deploy/docker/MIGRATION.md（后者对应 0.9.0 版本 Docker 服务端的安全加固迁移，可在 CHANGELOG.md 的 0.9.0 条目中看到其对 Breaking Changes 与迁移指南的引用方式）。

版本管理机制：三个文件联动

发布流程中的 “版本 bump” 在仓库中落地为三处联动，理解它们有助于贡献涉及版本号或构建的 PR：

1. 库版本单一事实源：crawl4ai/version.py 中定义 __version__ = "0.9.0"（稳定版），以及 __nightly_version__（nightly 构建时由构建过程设置）。pyproject.toml 通过 [tool.setuptools.dynamic] 的 version = {attr = "crawl4ai.__version__.__version__"} 从该属性读取版本——即只改 __version__.py 一个文件，PyPI 包版本即同步变化，这是发布流程 “version bump in code” 一步的落点。
2. Docker 镜像版本：Dockerfile 使用独立的 C4AI_VER 构建参数（当前 0.9.0），发布时需同步更新；docker-compose.yml 与 deploy/docker/README.md 中的版本引用同理。
3. 文档站版本标识：mkdocs.yml 的 site_name 携带版本号（当前 (v0.9.x)），发布说明则双份存放——docs/blog/ 下以 release-vX.Y.Z.md 命名（如 release-v0.9.0.md），同时拷贝到 docs/md_v2/blog/releases/ 供文档站展示。

pyproject.toml 还定义了 5 个命令行入口（crwl、crawl4ai-setup、crawl4ai-doctor、crawl4ai-migrate、crawl4ai-download-models），若贡献涉及 CLI 行为变更，PR 描述中应说明这些入口的受影响面。

双周发布管线：从 release 分支到 PyPI

对贡献者而言，合并进 develop 的改动默认进入下一次发布。原文档给出的发布管线（High-Level Overview）完整链路如下：

1. Preparation（准备）：从 develop 创建临时 release/vX.Y.Z 分支，把 next 中已就绪的特性合并进来；
2. Final Updates（收尾更新）：
   • 代码版本 bump（即上文的 __version__.py）；
   • 在 examples/ 下创建演示脚本，展示新功能；
   • 在 docs/blog/ 撰写发布说明——以第一人称（主维护者视角）写作，包含代码示例、影响面说明，破坏性变更时附迁移指南（可参考 docs/md_v2/blog/releases/v0.8.5.md 的结构：功能速览、逐项新特性说明、代码示例）；
   • 文档同步：README.md（亮点与版本引用）、mkdocs.yml（site_name 版本号）、发布说明拷贝至 docs/md_v2/blog/releases/；
   • Docker 同步：Dockerfile 的版本参数、docker-compose.yml、deploy/docker/README.md，并构建测试一个 release candidate 镜像（如 X.Y.Z-r1）；
3. Testing and Merge（测试与合并）：跑完整测试，提交后合并回 main 并打标签；
4. Publication（发布）：GitHub 上打 tag 发布（附说明）、发布到 PyPI、推送 Docker 镜像（稳定标签与 latest 均经测试后推送）；
5. Sync（回流）：back-merge 回 develop，重置 next 分支进入下一周期。

版本规则遵循语义化版本（Semantic Versioning）：MAJOR 表示破坏性变更，MINOR 表示新功能，PATCH 表示修复；必要时使用预发布号（如 -rc1）进行灰度测试。这与 CHANGELOG.md 头部声明的 “Keep a Changelog + Semantic Versioning” 格式约束一致。若贡献涉及 Docker 测试或文档，也可能被纳入发布收尾环节——原文档鼓励贡献者在 PR 中主动提出更新建议。

提交前检查清单与常见问题

PR 检查清单（原文档 Checklist 完整保留）

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

常见问题（Common Issues）

• 合并冲突：PR 前先用最新 develop rebase 自己的分支；
• Docker 构建：改动 Dockerfile 时，本地测试 amd64/arm64 多架构（对应 Dockerfile 中的 TARGETARCH 参数）；
• 版本一致性：任何版本引用都要符合语义化规则，与 __version__.py、Dockerfile、mkdocs.yml 保持联动。

沟通渠道

• 讨论与 bug 一律开 issue；
• 实时帮助通过项目 README 中列出的 Discord 社区；
• 每次发布后，公告同步推送至 GitHub、Discord 与社交媒体。

小结

Crawl4AI 的贡献体系用四条分支划清 “稳定 / 集成 / 实验 / 发布” 的边界，用固定目标分支 develop 降低协作成本，再用 cliff.toml 的 conventional commits 约束、三处联动的版本号（version.py、Dockerfile、mkdocs.yml）和双周节奏的 release 管线保证发布可预期。对贡献者而言，只要按六步流程操作、提交信息带上前缀、测试跑过 pytest，并在破坏性变更时附上迁移指南，即可顺利进入这条管线。