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/zulipZulip 是 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——如何提交易评审的 PRreview-process.md——PR 评审流程continuing-unfinished-work.md——接手他人未完成的工作zulipbot-usage.md——Zulipbot 机器人用法reporting-bugs.md、suggesting-features.md、reporting-security-vulnerabilities.mdcounting-contributions.md、licensing.md 等推荐的阅读节奏文档建议你按照以下时间节点或更早阅读对应章节阶段必读章节领取第一个 Issue 之前如何成为成功贡献者、AI 使用政策、快速上手、如何寻找 Issue开始做第一个 Issue 时获取帮助、最佳实践准备提交第一个 PR 时提交 Pull Request提交第一个 PR 之后第一个 Issue 之后如果读完全部文档仍卡住可以加入 Zulip 开发者社区提问——但发帖前务必先阅读社区的提问规范与问题该发到哪里的指引并遵守社区行为准则见仓库根目录的 CODE_OF_CONDUCT.md。成为成功贡献者的六项素质Zulip 官方文档明确列出一个高效贡献者应当具备六项核心素质从文档中学习Learn from documentation——Zulip 拥有超过 18.5 万词的贡献者文档项目期望你善加利用。文档总入口见 docs/index.md。追求理解Aim for understanding——要产出真正改进 Zulip 的代码你必须理解相关现有代码并设计出合理的一组改动。靠瞎试 / vibe coding碰巧跑通、再请维护者验证你自己都不懂的代码对项目毫无帮助。为工作自豪Take pride in your work——按提交纪律写出尽可能好的 commit按代码评审指南仔细自审并按PR 指南向维护者清晰解释改动。从反馈中学习Learn from feedback——每个 PR 都要经过严格的评审流程需要认真消化反馈、避免重蹈覆辙。有目的地沟通Communicate with intention——你发出的每条消息PR、社区提问等都在占用维护者的时间成功贡献者会按沟通准则清晰、简洁地表达不浪费社区时间制造 AI 垃圾内容。公开沟通Communicate in the open——技术与产品决策都在 Zulip 开发者社区和 GitHub 上公开讨论让所有人互相学习。此外贡献者需要具备与所改代码区域匹配的基础技术能力如果你发现自己频繁卡住建议先暂停贡献、补足相关软件工程技能。AI 使用政策与指南Zulip 在 contributing.md 中专门制定了 AI 使用政策核心原则是你始终需要理解并能够解释自己提出的改动——无论是否借助了 LLM。对为什么 X 是改进的回答永远不应该是我不确定AI 做的。警告不要提交一份你本人没有理解、没有亲自测试过的 AI 生成 PR这会浪费维护者的时间。违反该准则的 PR 将被直接关闭、不予评审。把 AI 当编码助手时的三条规则不要跳过熟悉代码库的环节。先用好 LLM 帮自己搜索和理解但不要轻信 LLM 对 Zulip 工作原理的描述——LLM 常常在文档已明确回答的细节上出错。把改动拆分为连贯的 commit即使这些代码是 LLM 一次生成的。不要简单让 LLM 添加代码注释——它很可能产出大量解释显而易见内容的文字。若用 LLM 写注释请给出非常具体的指令、要求简洁并仔细编辑结果。把 AI 用于沟通时的六条准则PR 描述不要复述代码里显而易见的信息如改了哪些文件、哪些函数而应聚焦为什么。回复评审意见时解释你的推理不要让 LLM 重新描述代码里已经能看到的东西。核实所有内容的准确性——无论是否由 LLM 生成误导性描述误述代码改动、影响或测试过程会让维护者无法评审。完整填写 PR 描述模板包括截图和自审清单不要用 LLM 输出直接覆盖模板。清晰简洁比完美语法更重要不必把写作都交给 LLM若请 LLM 润色明确要求不得变长。引用 LLM 答案不如链接一手资料源码、参考文档、Web 标准确需引用时放入引用块以区分。仓库根目录的 AGENTS.md 将上述理念进一步落地为面向 AI 编码代理的细则理解优先understand → propose → implement → verify 四步工作流、每个 commit 必须独立通过 lint/tests、禁止提交未测试代码、不得静默做设计/UX 决策、提交 AI PR 时以[ai]前缀标注等。快速上手环境准备用 Zulip 的方式学 GitZulip 使用 GitHub 做源码托管与代码评审熟悉 Git 是必须的。仓库 docs/git/ 目录下有完整的 Git 指南总览即使从未用过 Git 也能从零学起已有基础者则应重点阅读 Zulip 专用 Git 工具如 setup-git-repo 脚本可一键配置 pre-commit 钩子与仓库工具。服务端与 Web 应用开发环境按开发环境总览安装开发环境推荐用仓库根目录的 tools/provision 脚本自动化搭建依赖。熟悉开发环境的使用日常用 tools/run-dev 启动开发服务器。通读新应用功能教程了解代码库组织方式与定位代码的方法。从仓库结构可对照 AGENTS.md 的快速参考看本仓库核心目录为目录职责zerver/主 Django 应用models/数据模型、views/API 端点、lib/共享工具、tests/后端测试、webhooks/集成web/前端 TypeScript/JavaScriptsrc/主前端代码、styles/CSS、templates/前端模板、tests/前端测试templates/Jinja2/Handlebars 服务端模板tools/开发与测试脚本docs/ReadTheDocs 文档源开发中高频使用的命令均在 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。推荐的五步挑选流程找一个带help wanted标签、未被认领或疑似被放弃的 Issue。通读 Issue 描述并确保自己理解。若感觉可行在产品开发者社区或本地开发环境里实际摸索弄清该功能在整体中的位置若描述含糊可在 GitHub Issue 下提问他人也可能受益。找到心仪 Issue 后尽早动手用git grep定位需要修改的代码形成大致思路。若感到迷失也没关系换一个 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频道以名字为主题自我介绍。公开求助的标准流程先阅读社区指南与规范。决定发帖位置如果手头 Issue 关联了讨论线程通常那是提问的最佳位置否则按社区指引选择公开频道。选错也不必紧张版主可以把你的问题线程移动到合适的频道。写好问题遵循提问指南——先尽力自行解决含查阅文档与代码、定位卡住的确切点、提供适量上下文与明确请求不要问这个 Issue 怎么做这类泛泛的问题而要说明你的理解、尝试过什么、卡在哪里必要时附上 traceback。发送前复查确保问题对熟悉 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的规范写法**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.**Description正文**解释为什么与如何提供评审者和一年后的开发者需要的背景与动机与代码里可见的 diff 内容文件名、函数清单、更新了测试不要重复。若修复了 GitHub Issue在正文末尾写Fixes #123.避免Partially fixes #1234.这种写法GitHub 会忽略 partially 而自动关闭 Issue。正文与摘要之间用空行分隔按约 68–70 字符换行可添加Co-authored-by:行署名协作者。提交 Pull Request让 PR 易于评审reviewable-prs.md 将 PR 准备工作归纳为五个步骤写出清晰的代码确保自己理解它为什么能按预期工作若引入他人版权内容按 licensing.md 正确署名。组织你的改动把改动编排成一系列能讲述代码库将如何变化的 commit好的 commit 通常少于 100 行改动能拆就拆。记住你展示的是最终成果而非过程绝不要出现修复本 PR 前一个 commit 错误的 commit用git rebase -i修正原 commit。理想情况下维护者能先验证并合并前几个 commit、再对剩余部分提意见。解释你的改动在 PR 描述中给出总览、与既有计划如 Issue 描述的差异、你不确定的问题/决策并为所有视觉变更附上截图遵循视觉变更呈现指南CSS 改动还需提供像素级精确的 Before/After 对比。若有对应社区讨论双向交叉链接链接到具体消息更稳。自审按 code-reviewing.md 中评审自己的代码一节仔细自测并逐项勾选 PR 模板中的自审清单。提交评审确保通过全部 CI 测试维护者通常在测试通过后才评审若首次提交时还没准备好准备好后发一条清晰的评论说明改动并请求评审。六阶段评审流程review-process.md 描述了 PR 可能经历的评审阶段仓库用标签管理各阶段每个阶段的评审者在其无更多反馈时移除对应标签阶段对应标签说明产品评审product review审视产品设计是否需要修订必要时要求调整实现QAQA needed有用户可见改动的 PR 会做一轮脱离代码的测试初始代码评审—通常先由其他贡献者评审高效利用维护者时间维护者代码评审maintainer review维护者深入审查代码文档评审help center review/api docs review文档改动通常较晚评审等 UI 与代码趋于稳定集成评审integration review最终一轮由维护者完成并非每个 PR 都会经历全部阶段小改动通常很快。推进评审的要点尽可能吸收所有反馈完成后评论说明解决了哪些问题以及如何解决、还有哪些未处理的问题附相关讨论链接、必要时更新截图与手工测试信息一周无评论时可发一条简洁提醒。评审者提到的 follow-up后续工作应优先保证当前 PR 完成随后尽快处理没时间做就提 Issue 跟踪。第一个 Issue 之后找第二个 Issue 时建议优先看与上一个 Issue 相同area:标签的问题——可以复用你学习该区域代码的经验。成为核心开发者的常见路径正是逐步拥有一个或多个 area 标签对应区域的所有权。常见问题QA关于认领 Issue能做没有help wanted标签的 Issue 吗一般不能——该标签的用途就是标识开放给社区的 Issue。除非你在相关区域已有一个已合并的 PR、且该 Issue 有清晰的产品规格和无明显阻塞否则请勿认领。想认领的 Issue 已有人在做了换一个即可主仓库就有成百上千个可认领的或帮忙评审他们的工作。觉得 assignee 已不做了评论询问Hi someone! Are you still working on this one? Id 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 CodeGSoC导师组织每年夏季接纳 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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
Zulip 贡献指南全解析：从环境搭建到首个 Pull Request 的完整开源协作工作流
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/zulipZulip 是 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——如何提交易评审的 PRreview-process.md——PR 评审流程continuing-unfinished-work.md——接手他人未完成的工作zulipbot-usage.md——Zulipbot 机器人用法reporting-bugs.md、suggesting-features.md、reporting-security-vulnerabilities.mdcounting-contributions.md、licensing.md 等推荐的阅读节奏文档建议你按照以下时间节点或更早阅读对应章节阶段必读章节领取第一个 Issue 之前如何成为成功贡献者、AI 使用政策、快速上手、如何寻找 Issue开始做第一个 Issue 时获取帮助、最佳实践准备提交第一个 PR 时提交 Pull Request提交第一个 PR 之后第一个 Issue 之后如果读完全部文档仍卡住可以加入 Zulip 开发者社区提问——但发帖前务必先阅读社区的提问规范与问题该发到哪里的指引并遵守社区行为准则见仓库根目录的 CODE_OF_CONDUCT.md。成为成功贡献者的六项素质Zulip 官方文档明确列出一个高效贡献者应当具备六项核心素质从文档中学习Learn from documentation——Zulip 拥有超过 18.5 万词的贡献者文档项目期望你善加利用。文档总入口见 docs/index.md。追求理解Aim for understanding——要产出真正改进 Zulip 的代码你必须理解相关现有代码并设计出合理的一组改动。靠瞎试 / vibe coding碰巧跑通、再请维护者验证你自己都不懂的代码对项目毫无帮助。为工作自豪Take pride in your work——按提交纪律写出尽可能好的 commit按代码评审指南仔细自审并按PR 指南向维护者清晰解释改动。从反馈中学习Learn from feedback——每个 PR 都要经过严格的评审流程需要认真消化反馈、避免重蹈覆辙。有目的地沟通Communicate with intention——你发出的每条消息PR、社区提问等都在占用维护者的时间成功贡献者会按沟通准则清晰、简洁地表达不浪费社区时间制造 AI 垃圾内容。公开沟通Communicate in the open——技术与产品决策都在 Zulip 开发者社区和 GitHub 上公开讨论让所有人互相学习。此外贡献者需要具备与所改代码区域匹配的基础技术能力如果你发现自己频繁卡住建议先暂停贡献、补足相关软件工程技能。AI 使用政策与指南Zulip 在 contributing.md 中专门制定了 AI 使用政策核心原则是你始终需要理解并能够解释自己提出的改动——无论是否借助了 LLM。对为什么 X 是改进的回答永远不应该是我不确定AI 做的。警告不要提交一份你本人没有理解、没有亲自测试过的 AI 生成 PR这会浪费维护者的时间。违反该准则的 PR 将被直接关闭、不予评审。把 AI 当编码助手时的三条规则不要跳过熟悉代码库的环节。先用好 LLM 帮自己搜索和理解但不要轻信 LLM 对 Zulip 工作原理的描述——LLM 常常在文档已明确回答的细节上出错。把改动拆分为连贯的 commit即使这些代码是 LLM 一次生成的。不要简单让 LLM 添加代码注释——它很可能产出大量解释显而易见内容的文字。若用 LLM 写注释请给出非常具体的指令、要求简洁并仔细编辑结果。把 AI 用于沟通时的六条准则PR 描述不要复述代码里显而易见的信息如改了哪些文件、哪些函数而应聚焦为什么。回复评审意见时解释你的推理不要让 LLM 重新描述代码里已经能看到的东西。核实所有内容的准确性——无论是否由 LLM 生成误导性描述误述代码改动、影响或测试过程会让维护者无法评审。完整填写 PR 描述模板包括截图和自审清单不要用 LLM 输出直接覆盖模板。清晰简洁比完美语法更重要不必把写作都交给 LLM若请 LLM 润色明确要求不得变长。引用 LLM 答案不如链接一手资料源码、参考文档、Web 标准确需引用时放入引用块以区分。仓库根目录的 AGENTS.md 将上述理念进一步落地为面向 AI 编码代理的细则理解优先understand → propose → implement → verify 四步工作流、每个 commit 必须独立通过 lint/tests、禁止提交未测试代码、不得静默做设计/UX 决策、提交 AI PR 时以[ai]前缀标注等。快速上手环境准备用 Zulip 的方式学 GitZulip 使用 GitHub 做源码托管与代码评审熟悉 Git 是必须的。仓库 docs/git/ 目录下有完整的 Git 指南总览即使从未用过 Git 也能从零学起已有基础者则应重点阅读 Zulip 专用 Git 工具如 setup-git-repo 脚本可一键配置 pre-commit 钩子与仓库工具。服务端与 Web 应用开发环境按开发环境总览安装开发环境推荐用仓库根目录的 tools/provision 脚本自动化搭建依赖。熟悉开发环境的使用日常用 tools/run-dev 启动开发服务器。通读新应用功能教程了解代码库组织方式与定位代码的方法。从仓库结构可对照 AGENTS.md 的快速参考看本仓库核心目录为目录职责zerver/主 Django 应用models/数据模型、views/API 端点、lib/共享工具、tests/后端测试、webhooks/集成web/前端 TypeScript/JavaScriptsrc/主前端代码、styles/CSS、templates/前端模板、tests/前端测试templates/Jinja2/Handlebars 服务端模板tools/开发与测试脚本docs/ReadTheDocs 文档源开发中高频使用的命令均在 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。推荐的五步挑选流程找一个带help wanted标签、未被认领或疑似被放弃的 Issue。通读 Issue 描述并确保自己理解。若感觉可行在产品开发者社区或本地开发环境里实际摸索弄清该功能在整体中的位置若描述含糊可在 GitHub Issue 下提问他人也可能受益。找到心仪 Issue 后尽早动手用git grep定位需要修改的代码形成大致思路。若感到迷失也没关系换一个 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频道以名字为主题自我介绍。公开求助的标准流程先阅读社区指南与规范。决定发帖位置如果手头 Issue 关联了讨论线程通常那是提问的最佳位置否则按社区指引选择公开频道。选错也不必紧张版主可以把你的问题线程移动到合适的频道。写好问题遵循提问指南——先尽力自行解决含查阅文档与代码、定位卡住的确切点、提供适量上下文与明确请求不要问这个 Issue 怎么做这类泛泛的问题而要说明你的理解、尝试过什么、卡在哪里必要时附上 traceback。发送前复查确保问题对熟悉 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的规范写法**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.**Description正文**解释为什么与如何提供评审者和一年后的开发者需要的背景与动机与代码里可见的 diff 内容文件名、函数清单、更新了测试不要重复。若修复了 GitHub Issue在正文末尾写Fixes #123.避免Partially fixes #1234.这种写法GitHub 会忽略 partially 而自动关闭 Issue。正文与摘要之间用空行分隔按约 68–70 字符换行可添加Co-authored-by:行署名协作者。提交 Pull Request让 PR 易于评审reviewable-prs.md 将 PR 准备工作归纳为五个步骤写出清晰的代码确保自己理解它为什么能按预期工作若引入他人版权内容按 licensing.md 正确署名。组织你的改动把改动编排成一系列能讲述代码库将如何变化的 commit好的 commit 通常少于 100 行改动能拆就拆。记住你展示的是最终成果而非过程绝不要出现修复本 PR 前一个 commit 错误的 commit用git rebase -i修正原 commit。理想情况下维护者能先验证并合并前几个 commit、再对剩余部分提意见。解释你的改动在 PR 描述中给出总览、与既有计划如 Issue 描述的差异、你不确定的问题/决策并为所有视觉变更附上截图遵循视觉变更呈现指南CSS 改动还需提供像素级精确的 Before/After 对比。若有对应社区讨论双向交叉链接链接到具体消息更稳。自审按 code-reviewing.md 中评审自己的代码一节仔细自测并逐项勾选 PR 模板中的自审清单。提交评审确保通过全部 CI 测试维护者通常在测试通过后才评审若首次提交时还没准备好准备好后发一条清晰的评论说明改动并请求评审。六阶段评审流程review-process.md 描述了 PR 可能经历的评审阶段仓库用标签管理各阶段每个阶段的评审者在其无更多反馈时移除对应标签阶段对应标签说明产品评审product review审视产品设计是否需要修订必要时要求调整实现QAQA needed有用户可见改动的 PR 会做一轮脱离代码的测试初始代码评审—通常先由其他贡献者评审高效利用维护者时间维护者代码评审maintainer review维护者深入审查代码文档评审help center review/api docs review文档改动通常较晚评审等 UI 与代码趋于稳定集成评审integration review最终一轮由维护者完成并非每个 PR 都会经历全部阶段小改动通常很快。推进评审的要点尽可能吸收所有反馈完成后评论说明解决了哪些问题以及如何解决、还有哪些未处理的问题附相关讨论链接、必要时更新截图与手工测试信息一周无评论时可发一条简洁提醒。评审者提到的 follow-up后续工作应优先保证当前 PR 完成随后尽快处理没时间做就提 Issue 跟踪。第一个 Issue 之后找第二个 Issue 时建议优先看与上一个 Issue 相同area:标签的问题——可以复用你学习该区域代码的经验。成为核心开发者的常见路径正是逐步拥有一个或多个 area 标签对应区域的所有权。常见问题QA关于认领 Issue能做没有help wanted标签的 Issue 吗一般不能——该标签的用途就是标识开放给社区的 Issue。除非你在相关区域已有一个已合并的 PR、且该 Issue 有清晰的产品规格和无明显阻塞否则请勿认领。想认领的 Issue 已有人在做了换一个即可主仓库就有成百上千个可认领的或帮忙评审他们的工作。觉得 assignee 已不做了评论询问Hi someone! Are you still working on this one? Id 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 CodeGSoC导师组织每年夏季接纳 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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考