企业官网建设流程全解析

Zulip 贡献指南全解析：从环境搭建到首个 Pull Request 的完整开源协作工作流

【免费下载链接】zulipZulip server and web application. Open-source team chat that helps teams stay productive and focused.项目地址: https://gitcode.com/GitHub_Trending/zu/zulip

Zulip 是 GitHub 上广受欢迎的开源团队聊天应用（服务器与 Web 应用均在本仓库中），它拥有超过 18.5 万词的开发者文档，并以"文档驱动"的方式培养新贡献者。本文以仓库根目录下的 docs/contributing/contributing.md 为主线，结合 docs/contributing/ 目录下的全套协作指南与仓库实际工具链，系统讲解 Zulip 的贡献流程：如何准备开发环境、如何挑选并认领 Issue、如何写出符合 commit discipline 的提交、如何通过六阶段评审流程成功合入首个 Pull Request，以及 Zulip 对 AI 辅助编码的使用政策。读完本文，你将掌握一套可直接照做的开源贡献实操路线图。

文档驱动的贡献者培养体系

Zulip 采用"以文档为准"（documentation-based）的新人引导方式：这份contributing.md就是你上手时的总入口，任何时刻感到迷茫都可以回到本页，从常见问题或它指向的众多参考资料中寻找答案。

文档全景：贡献者指南目录

文档目录（docs/contributing/index.md）以 toctree 形式汇总了整套贡献者指南，除本文外还包括：

• how-we-communicate.md——社区沟通准则
• asking-great-questions.md——如何提出好问题
• commit-discipline.md——提交纪律
• code-style.md——代码风格
• presenting-visual-changes.md——视觉变更的截图呈现
• code-reviewing.md——代码评审
• reviewable-prs.md——如何提交易评审的 PR
• review-process.md——PR 评审流程
• continuing-unfinished-work.md——接手他人未完成的工作
• zulipbot-usage.md——Zulipbot 机器人用法
• reporting-bugs.md、suggesting-features.md、reporting-security-vulnerabilities.md
• counting-contributions.md、licensing.md 等

推荐的阅读节奏

文档建议你按照以下时间节点（或更早）阅读对应章节：

如果读完全部文档仍卡住，可以加入 Zulip 开发者社区提问——但发帖前务必先阅读社区的提问规范与"问题该发到哪里"的指引，并遵守社区行为准则（见仓库根目录的 CODE_OF_CONDUCT.md）。

成为成功贡献者的六项素质

Zulip 官方文档明确列出，一个高效贡献者应当具备六项核心素质：

1. 从文档中学习（Learn from documentation）——Zulip 拥有超过 18.5 万词的贡献者文档，项目期望你善加利用。文档总入口见 docs/index.md。
2. 追求理解（Aim for understanding）——要产出真正改进 Zulip 的代码，你必须理解相关现有代码，并设计出合理的一组改动。靠"瞎试 / vibe coding"碰巧跑通、再请维护者验证你自己都不懂的代码，对项目毫无帮助。
3. 为工作自豪（Take pride in your work）——按提交纪律写出尽可能好的 commit，按代码评审指南仔细自审，并按PR 指南向维护者清晰解释改动。
4. 从反馈中学习（Learn from feedback）——每个 PR 都要经过严格的评审流程，需要认真消化反馈、避免重蹈覆辙。
5. 有目的地沟通（Communicate with intention）——你发出的每条消息（PR、社区提问等）都在占用维护者的时间，成功贡献者会按沟通准则清晰、简洁地表达，不浪费社区时间制造 "AI 垃圾内容"。
6. 公开沟通（Communicate in the open）——技术与产品决策都在 Zulip 开发者社区和 GitHub 上公开讨论，让所有人互相学习。

此外，贡献者需要具备与所改代码区域匹配的基础技术能力；如果你发现自己频繁卡住，建议先暂停贡献、补足相关软件工程技能。

AI 使用政策与指南

Zulip 在 contributing.md 中专门制定了 AI 使用政策，核心原则是：你始终需要理解并能够解释自己提出的改动——无论是否借助了 LLM。对"为什么 X 是改进？"的回答，永远不应该是"我不确定，AI 做的"。

警告：不要提交一份你本人没有理解、没有亲自测试过的 AI 生成 PR，这会浪费维护者的时间。违反该准则的 PR 将被直接关闭、不予评审。

把 AI 当编码助手时的三条规则

1. 不要跳过熟悉代码库的环节。先用好 LLM 帮自己搜索和理解，但不要轻信 LLM 对 Zulip 工作原理的描述——LLM 常常在文档已明确回答的细节上出错。
2. 把改动拆分为连贯的 commit，即使这些代码是 LLM 一次生成的。
3. 不要简单让 LLM 添加代码注释——它很可能产出大量解释显而易见内容的文字。若用 LLM 写注释，请给出非常具体的指令、要求简洁，并仔细编辑结果。

把 AI 用于沟通时的六条准则

1. PR 描述不要复述代码里显而易见的信息（如改了哪些文件、哪些函数），而应聚焦"为什么"。
2. 回复评审意见时解释"你的"推理，不要让 LLM 重新描述代码里已经能看到的东西。
3. 核实所有内容的准确性——无论是否由 LLM 生成，误导性描述（误述代码改动、影响或测试过程）会让维护者无法评审。
4. 完整填写 PR 描述模板，包括截图和自审清单，不要用 LLM 输出直接覆盖模板。
5. 清晰简洁比完美语法更重要，不必把写作都交给 LLM；若请 LLM 润色，明确要求不得变长。
6. 引用 LLM 答案不如链接一手资料（源码、参考文档、Web 标准）；确需引用时放入引用块以区分。

仓库根目录的 AGENTS.md 将上述理念进一步落地为面向 AI 编码代理的细则：理解优先（understand → propose → implement → verify 四步工作流）、每个 commit 必须独立通过 lint/tests、禁止提交未测试代码、不得静默做设计/UX 决策、提交 AI PR 时以[ai]前缀标注等。

快速上手：环境准备

用 Zulip 的方式学 Git

Zulip 使用 GitHub 做源码托管与代码评审，熟悉 Git 是必须的。仓库 docs/git/ 目录下有完整的 Git 指南（总览），即使从未用过 Git 也能从零学起；已有基础者则应重点阅读 Zulip 专用 Git 工具（如 setup-git-repo 脚本，可一键配置 pre-commit 钩子与仓库工具）。

服务端与 Web 应用开发环境

1. 按开发环境总览安装开发环境（推荐用仓库根目录的 tools/provision 脚本自动化搭建依赖）。
2. 熟悉开发环境的使用（日常用 tools/run-dev 启动开发服务器）。
3. 通读新应用功能教程，了解代码库组织方式与定位代码的方法。

从仓库结构（可对照 AGENTS.md 的快速参考）看，本仓库核心目录为：

开发中高频使用的命令（均在 tools/ 下）：

./tools/provision # 搭建开发环境（依赖过期时需重跑） ./tools/run-dev # 启动开发服务器 ./tools/lint # 运行全部 linter（含 mypy 类型检查） ./tools/test-backend # 运行 Python 后端测试 ./tools/test-js-with-node # 运行前端 JavaScript 测试 ./tools/run-mypy # 运行类型检查器 git grep "pattern" # 在代码库中搜索模式（高频使用！）

其他客户端

• Flutter 移动端：按 zulip-flutter 项目 README 搭建环境；用图形化 Git 查看器（如gitk）或git log -p（阅读技巧见 docs/git/reading-history.md）阅读近期提交，并沿感兴趣代码用 IDE 跳转探索。
• 桌面端（zulip-desktop）：按其development.md搭建环境。
• 终端端（zulip-terminal）：按其 README 中的"Setting up a development environment"章节搭建。

挑选你的第一个 Issue

注意：项目维护者无法为新人逐一推荐 Issue——学会自己找到可做的 Issue，本身就是新贡献者需要掌握的一项技能。

去哪里找

主仓库（服务端与 Web 应用）就有数百个带help wanted标签的开放 Issue。查找途径：

• help wanted标签：表示开放给社区贡献。
• no:assignee过滤器：找出未被认领的 Issue；已被分配但无人继续做的也可接手。
• good first issue标签：部分仓库用它标记对新贡献者尤其友好的问题。
• area:系列标签：所有 Issue 按 admin、compose、emoji、hotkeys、i18n、onboarding、search 等领域分区，点开感兴趣的area:标签即可看到相关全部 Issue。
• 除非你完全理解其难度且极有信心，否则避开difficult标签的 Issue。

推荐的五步挑选流程

1. 找一个带help wanted标签、未被认领或疑似被放弃的 Issue。
2. 通读 Issue 描述并确保自己理解。
3. 若感觉可行，在产品（开发者社区或本地开发环境）里实际摸索，弄清该功能在整体中的位置；若描述含糊，可在 GitHub Issue 下提问（他人也可能受益）。
4. 找到心仪 Issue 后尽早动手：用git grep定位需要修改的代码，形成大致思路。
5. 若感到迷失也没关系，换一个 Issue 重复上述过程——探索本身就是学习。

判断 Issue 是否被放弃

满足以下两条即可认为被放弃：无近期贡献者活动；没有开放 PR，或开放 PR 仍需返工（如需回应评审意见或通过测试）才能进入评审。

注意：步骤 1–4 期间你并未认领该 Issue；只有在确信自己能有效解决时再正式认领。

认领 Issue 的两种方式

主仓库与 Zulip Terminal 仓库：使用 Zulipbot

服务端/Web 主仓库与 Terminal 仓库部署了名为@zulipbot的 GitHub 工作流机器人，用于弥补 GitHub 权限与通知机制的局限，让任何贡献者都能自助认领、打标签，而无需仓库写权限。完整用法见 zulipbot-usage.md，核心操作：

• 认领：在 Issue 下评论@zulipbot claim，机器人会立即把你设为 assignee 并打上in progress标签；新贡献者还会被授予只读协作者权限并收到欢迎消息。自己开的 Issue 也可在正文中包含@zulipbot claim直接认领。
• 放弃：评论@zulipbot abandon。
• 打标签：在 Issue 评论或正文中写@zulipbot add "bug" "help wanted"（标签需用双引号包裹）；写错的标签可用@zulipbot remove "..."移除。
• 找未认领 Issue：用 GitHub 搜索过滤器-label: "in progress"或no:assignee。
• 加入 area 标签团队：加入 Zulip 组织的 Server area label teams 后，可接收对应area:标签下 Issue 与相关 PR 的通知。
• 闲置处理：已认领 Issue 一周无更新时，Zulipbot 会评论询问 assignee 是否仍在工作；3 天内未回复，将自动移除 assignee 与in progress标签，把 Issue 释放给其他人。

注意：新贡献者在首个 PR 合并前只能同时认领一个 Issue，这是为了鼓励先完成手头工作。若在等待评审期间想接手新 Issue，可在目标 Issue 下评论说明情况。

其他 Zulip 仓库：自助认领

在 zulip-flutter 等其他仓库没有机器人，做法是：找到心仪 Issue 后，在 Issue 线程下评论说明你已开始工作并希望认领，并在评论中描述你在前述步骤中学到的东西（要修改哪部分代码、计划如何解决）。无需 @ 提及 Issue 创建者，也无需重复发到多个地方。

获取帮助

在推进 PR 过程中遇到问题，最好的去处是 Zulip 开发者社区（可在#new members频道以名字为主题自我介绍）。公开求助的标准流程：

1. 先阅读社区指南与规范。
2. 决定发帖位置：如果手头 Issue 关联了讨论线程，通常那是提问的最佳位置；否则按社区指引选择公开频道。选错也不必紧张，版主可以把你的问题线程移动到合适的频道。
3. 写好问题：遵循提问指南——先尽力自行解决（含查阅文档与代码）、定位卡住的确切点、提供适量上下文与明确请求；不要问"这个 Issue 怎么做"这类泛泛的问题，而要说明你的理解、尝试过什么、卡在哪里，必要时附上 traceback。
4. 发送前复查：确保问题对熟悉 Zulip 但不了解你工作细节的人也能读懂。

措辞良好的问题通常在 1–2 个工作日内得到回复，无需 @ 任何人——维护者会密切关注所有讨论。

最佳实践清单

• 提出好问题：见 asking-great-questions.md。
• 修炼提交纪律：见 commit-discipline.md（下一节详述）。
• 提交经过仔细测试的代码：可参考 code-reviewing.md 中的"如何评审代码"章节来审视自己或他人的工作。
• 让 PR 易于评审：见 reviewable-prs.md 与视觉变更呈现指南。
• 清楚描述实现内容与原因：若实现与 Issue 描述有出入或是部分实现，务必在 PR 中说明。
• 对评审反馈保持响应：吸收或回应所有建议；若几天内无法处理，留言说明。
• 在社区保持友善互助。

提交纪律：每个 commit 是一个"最小连贯想法"

Zulip 遵循 Git 项目自身的实践——"每个 commit 是一个最小连贯的想法"（Each commit is a minimal coherent idea），并用git rebase -i随时调整提交结构。详见 commit-discipline.md，核心要点：

每个 commit 必须：

• 通过测试（测试更新与代码改动放在同一 commit，而不是单独的"修复上个 commit 破坏的测试"）。
• 不使 Zulip 变差（例如可以先加后端能力而无前端入口，但反过来不行）。
• 可单独安全部署，或在 commit message 中详细解释为何不能（可加[manual]标记）；新 API 端点的安全检查必须从一开始就在，不能后补。
• 错误处理通常与可能触发错误的代码一起提交；TODO 注释应放在引入该问题/功能的 commit 中。

commit 应尽量最小：重构、加测试、重命名、移动代码等不改变功能的改动应做成可独立合并的准备性 commit；文件搬移、不同的重构、不同的功能应分属不同 commit。若你发现自己写了一条"罗列多件不相似事情"的 commit message，那通常说明应该拆成多个 commit。全新功能则不必过度拆分到每个子特性一个 commit，但 2000 行的巨型新代码也不利于评审。

提交信息（commit message）的规范写法：

1. **Summary（摘要）**由两部分组成：
   • 第一部分是 1–2 个小写单词加冒号，指明改动的产品区域，如settings:、message feed:、compose:、left sidebar:、recent:、search:、markdown:、integrations:、docs:等；纯 CSS 改动可用css:，或用主要修改的技术子系统名（如realm_icon而非完整路径）。永远不要用bug、fix、refactor这类泛词。
   • 第二部分是一个以祈使动词开头的完整短句（如 fix、add、change、rename），规范大小写与标点，避免缩写；整个 summary 不超过 72 字符。
   • 优秀示例：provision: Improve performance of installing npm.、channel: Discard all HTTP responses while reloading.、integrations: Add GitLab integration.、gather_subscriptions: Fix exception handling bad input.
2. **Description（正文）**解释"为什么"与"如何"，提供评审者和一年后的开发者需要的背景与动机；与代码里可见的 diff 内容（文件名、函数清单、"更新了测试"）不要重复。若修复了 GitHub Issue，在正文末尾写Fixes #123.（避免Partially fixes #1234.这种写法，GitHub 会忽略 "partially" 而自动关闭 Issue）。正文与摘要之间用空行分隔，按约 68–70 字符换行；可添加Co-authored-by:行署名协作者。

提交 Pull Request

让 PR 易于评审

reviewable-prs.md 将 PR 准备工作归纳为五个步骤：

1. 写出清晰的代码：确保自己理解它为什么能按预期工作；若引入他人版权内容，按 licensing.md 正确署名。
2. 组织你的改动：把改动编排成一系列能讲述"代码库将如何变化"的 commit（好的 commit 通常少于 100 行改动，能拆就拆）。记住你展示的是最终成果而非过程，绝不要出现"修复本 PR 前一个 commit 错误"的 commit，用git rebase -i修正原 commit。理想情况下，维护者能先验证并合并前几个 commit、再对剩余部分提意见。
3. 解释你的改动：在 PR 描述中给出总览、与既有计划（如 Issue 描述）的差异、你不确定的问题/决策，并为所有视觉变更附上截图（遵循视觉变更呈现指南，CSS 改动还需提供像素级精确的 Before/After 对比）。若有对应社区讨论，双向交叉链接（链接到具体消息更稳）。
4. 自审：按 code-reviewing.md 中"评审自己的代码"一节仔细自测，并逐项勾选 PR 模板中的自审清单。
5. 提交评审：确保通过全部 CI 测试（维护者通常在测试通过后才评审）；若首次提交时还没准备好，准备好后发一条清晰的评论说明改动并请求评审。

六阶段评审流程

review-process.md 描述了 PR 可能经历的评审阶段，仓库用标签管理各阶段（每个阶段的评审者在其无更多反馈时移除对应标签）：

并非每个 PR 都会经历全部阶段，小改动通常很快。推进评审的要点：尽可能吸收所有反馈；完成后评论说明解决了哪些问题（以及如何解决）、还有哪些未处理的问题（附相关讨论链接）、必要时更新截图与手工测试信息；一周无评论时可发一条简洁提醒。评审者提到的 "follow-up"（后续工作）应优先保证当前 PR 完成，随后尽快处理；没时间做就提 Issue 跟踪。

第一个 Issue 之后

找第二个 Issue 时，建议优先看与上一个 Issue 相同area:标签的问题——可以复用你学习该区域代码的经验。成为核心开发者的常见路径，正是逐步"拥有"一个或多个 area 标签对应区域的所有权。

常见问题（Q&A）

关于认领 Issue

• 能做没有help wanted标签的 Issue 吗？一般不能——该标签的用途就是标识开放给社区的 Issue。除非你在相关区域已有一个已合并的 PR、且该 Issue 有清晰的产品规格和无明显阻塞，否则请勿认领。
• 想认领的 Issue 已有人在做了？换一个即可（主仓库就有成百上千个可认领的）；或帮忙评审他们的工作。
• 觉得 assignee 已不做了？评论询问："Hi @someone! Are you still working on this one? I'd like to pick it up if not."；2–3 天无回复即可评论声明开工并提交 PR；若原 assignee 抢先提交了 PR，帮忙评审或按需提交不同方案的 PR 都是好的贡献。
• 已有针对该 Issue 的 PR？见接手未完成工作指南。
• 考虑期间被别人认领了？帮忙评审对方 PR，或在同区域另找一个help wantedIssue。
• 能做老 Issue 吗？可以。若上下文已变化（如 UI 变了），尽量套用当前模式并在 PR 描述中说明与规格的差异；修 bug 先验证能否复现（不能复现就在 Issue 下说明测试方法与所见并附图）；超过数年的重大项目，建议先在社区讨论线程确认思路是否已变。
• 能自创功能来做吗？欢迎基于使用体验提出建议，按报告 bug与建议功能的流程走；但不要只是为了找活干而提建议。
• 等首轮反馈时该做什么？阅读 Zulip 代码库与实践（本文档、已合并 PR、社区讨论），这会让未来的贡献更高效。
• 等下一轮评审期间能接新 Issue 吗？确保 PR 可评审并至少经历一轮维护者反馈后再接第二个 Issue；若 Zulipbot 不允许认领，可在目标 Issue 下评论说明其他工作状态（附所有开放 PR 链接）并请求分配。处理在途 PR 的反馈永远优先于开新 PR。

关于评审流程

• "我的 PR 已完成但还没合并，怎么回事？"依次检查：① 是否已处理全部反馈（含提交纪律意见）且自动化测试通过；② 是否评论说明已处理完毕并请求再次评审；③ 理解初轮评审与最终合并之间可能存在暂停，可并行做其他 Issue；④ 若已准备好却一两周无进展，发评论总结评审状态并说明在等待；⑤ 维护者也是普通人，可能忙于其他工作甚至休假，最终阶段偶尔需要数周才能合并。

暑期与 Outreach 项目

Zulip 自 2016 年起每年作为 Google Summer of Code（GSoC）导师组织，每年夏季接纳 10–20 名参与者；历史上还参与过 Google Code-In、Outreachy，并接待过来自哈佛、MIT、斯坦福的暑期实习生。详见 outreach 项目总览。大部分项目参与者会长期留在社区，许多人后来成为核心团队成员。无论以何种方式贡献，本文介绍的工作流——理解代码、挑选与认领 Issue、遵守提交纪律、走完评审流程——都是你与 Zulip 社区协作的地基。

【免费下载链接】zulipZulip server and web application. Open-source team chat that helps teams stay productive and focused.项目地址: https://gitcode.com/GitHub_Trending/zu/zulip