进阶 docs.openwebui.com 2026-10-22 19:22:27 · 24 阅读

第16章 Open WebUI 第16章:贡献指南

Contributing 助力构建人人享有的 AI 界面。 Open WebUI 是一个独立项目,由一支小型专职核心团队建设与维护。最有帮助的贡献方式包括:测试开发构建、提交清晰的 bug 报告、在 Discussions 中说明使用场景、改进文档以及翻译界面。维护者在内部评估并开发代码变更;代码 Pull Request(PR)需获得维护者的明确请求方可发起,仅限 i18n/本地化修改除外。本页介绍如何参与项目以及相关的预期规范。 行为准则​ 所有贡献者和社区参与者都必须遵守行为准则。我们实行零容忍政策:任何不尊重、强求或敌对行为都会立即采取措施处理,恕不事先警告。 Open WebUI 由小型核心团队领导,并得到整个项目中贡献者的支持。请以专业和尊重的态度对待每一次互动。 贡献方式​ 测试开发分支​ 最有价值的贡献之一完全不需要写代码。运行 dev 分支,将其作为日常使用工具,并报告发现的问题。 docker run -d -p 3000:8080 -v open-webui:/app/backend/data --name open-webui ghcr.io/open-webui/open-webui:dev dev 分支更新频繁,请定期拉取最新代码。如果不习惯使用 Docker,请遵循 Developing Open WebUI 指南进行操作。 在 GitHub 上提交问题,并提供清晰的复现步骤。社区测试有助于我们交付高质量版本。 提交代码​ 由于外部实现通常需要经过大量重构才能契合项目需求,因此我们在内部开发和优化解决方案。仅在接受到明确请求时,或修改仅限于 i18n/本地化时,我们才接受代码 PR。此要求涵盖 bug 修复、功能特性、重构、依赖项变更、UI 变更及仅测试变更,无论补丁大小、是否通过检查,也不管代码是手写还是借助 AI 生成。对一个已确认的 bug 的回应或对某个想法的积极反馈,并不等同于请求实现。未遵循此流程发起的 PR 通常会被直接关闭且不予审阅。 我们监控并核实每个问题,往往在内部已有正在工作的解决方案,只是在评估和完善方案期间尚未推送。问题保持开放状态且无公开回复或关联 PR,并不意味着它被忽视或可供认领。一个可用的修复方案必须契合项目的架构、现有行为以及正在进行的工作。评估过程经常会改变方案的适用范围和位置:界面中的某个症状可能源于共享状态、API 契约或特定供应商的行为;而添加新设置可能适配某种工作流却牺牲了其他工作流。解决当下症状只是工作的一部分。公共仓库的活动无法展示所有正在进行的研究或实现,未经请求的 PR 常常重复已有的工作,同时引入需要协调的另一套方案。维护者需要在发布结果前拥有完成该评估的空间。 明确请求的要求确立了由谁决定哪些实现工作将进入项目以及何时进入。未经请求的 PR 在维护者同意那些决策是项目所需之前,就已经在代码中内嵌了范围、设计和权衡。审阅这样的 PR 会将开放的设计问题变成对现有实现的谈判。作者的投入会产生保留该方法的压力,即便正确的结果可能是不同的设计、更小的变更,甚至不添加任何内容。我们需要根据项目需求做出这些决策。维护者的请求确立了在他人投入之前,我们已识别出有用的外部工作并同意其目的和范围。 这就是为什么此要求即使对优秀的代码也适用。如果所有未经请求的 PR 都可因“可能有用的理由”接受审阅,我们就必须进行该审阅才能决定此要求是否适用。提交规则将毫无作用。我们不运营一个通用的、用于审阅独立选择实现的队列。我们根据项目优先级选择工作,并在贡献有助于该工作时请求贡献。干净的 diff、通过的检查或提出修改的意愿,都不能替代这一决策。即使具备审阅能力,这仍是我们的开发流程。 审阅外部实现、解释所需变更并协调连续修订,通常比在内部开发解决方案耗费更多精力。碎片化的提交历史、未变基的分支、未解决的冲突、不相关的编辑以及未经核实的 AI 生成说明,都增加了额外工作。维护者仍须重建假设、评估广泛影响,并充分理解最终实现以承担其责任。这项工作需要占用处理回归、安全修复和发布所需的同等注意力。该要求防止了计划外的实现审阅决定注意力的分配。 代码一经发布,团队便需在后续版本中对其行为负责。我们需要在必要时保持兼容性,诊断故障,维护文档和回归覆盖,并随着周围系统的演进而适应变更。每个新的依赖、设置和抽象都会增加责任,用户也会围绕我们接受的行为构建工作流。后期移除不合适的变更会带来自身的兼容性和迁移成本。对后果负责的人员必须在实现开始前决定项目承担哪些承诺。杰出的工作会在维护者主动发起时考虑;贡献者不应将对自己补丁的评估视为绕过流程的许可。 对于新编写或重写的自动化测试(包括 fixtures、快照和测试基础设施),我们也要求明确的请求。请求实现修复并不包含请求添加测试套件。当代码和测试源于相同假设时,它们可能互相吻合却都偏离了预期行为。基于当前输出得出的断言可能固化错误;模拟对象可能移除了故障发生的集成点;快照可能记录了错误结果。绑定内部函数调用的测试可能在检测到用户可见回归之前阻碍健全的重构。通过此类测试会产生虚假的安全感,而更多的断言和更高的覆盖率并不能说明是否检查了正确行为。 这些测试成为另一个需要调查、重写和维护的实现。在依赖它们之前,我们必须核实其预期结果、假设以及检测原始故障的能力。维护者在内部确定预期行为后选择持久的回归覆盖,并在外部测试工作服务于该计划时请求此类贡献。对于被请求的 PR,请提供来自运行中应用程序的可复现证据:设置、确切步骤、预期行为以及变更前后的观察结果。包含相关日志、截图或录屏,运行与变更相关的现有检查,并报告故障及无法核实的内容。切勿移除、禁用或削弱现有测试以使变更通过。手动核实或通过测试套件都不能替代对方案及其广泛影响的审阅。 公共源代码和贡献接收是两个独立的项目决策。SQLite 将自己描述为“开源,而非开放贡献”:其限制保护了代码的公共领域状态,其文档解释说概念验证补丁可以从零重写。SQLite 有正式的接收贡献代码流程。这里的类比在于,有用的报告和参考实现可以为解决方案提供信息,同时维护者保留对发布内容的控制权。Open WebUI 的理由涉及开发能力、架构一致性和长期所有权;SQLite 的公共领域要求则具体针对 SQLite。 tldraw 在 2026 年 1 月的政策公告中描述了关闭外部 PR 并有选择地重新考虑正在审核的工作,理由是 AI 生成的提交、上下文不完整以及作者后续跟进有限。其贡献指南引导人们关注问题和分支引用,同时声明不接受贡献。Clojure 的开发政策通过其自身流程接受补丁,但将方向决策权交给核心团队,并要求功能提案在进入实现前建立问题并比较替代方案。这些都是具有不同治理和许可安排的不同政策。它们说明了社区输入如何为项目提供参考,而维护者则决定其设计和贡献流程。Open WebUI 保留了明确请求的工作和本地化贡献的路径。 如果你真的想帮助 Open WebUI,请以项目的需求以及维护者执行你贡献的能力作为衡量其价值的标准。精确的复现、经过仔细调查的报告或对工作流有用的说明,都能在没有以你名义合并的 PR 的情况下改进项目。请做好维护者以不同方式解决问题、在内部实现解决方案或决定提议变更不属于项目范围的准备。帮助意味着即使你的代码未被使用,也支持该结果。通过 Issues 提交可复现的 bug,通过 Discussions 提交提案。搜索现有报告,检查当前 release 和 dev,并提供受影响的工作流、预期与实际结果以及相关证据。通过私密的安全报告流程报告安全隐患。当有助于澄清问题时,在相关报告中分享实现笔记、本地 diff、补丁或分支引用;不要通过发起 PR 来获取参考代码的关注度。后续跟进提供有用证据并尊重团队的优先级。报告不保证回复、实现或时间表,重复催促或重复提交会占用工作时间。 当我们请求 PR 时,目的是完成项目已同意需要的工作。请将此目的置于对实现的个人偏好、贡献大小或确保合并之上。遵循 Pull Request 模板,针对 dev,完成贡献者许可协议(CLA),并在 Maintainer Request 部分链接维护者的请求。遵循现有模式,记录验证过程,并保持在商定范围内。如果方案需要变更,回到讨论中;接受审阅可能导致重写或决定不继续。邀请不授权不相关的变更或未经请求的测试,也不保证会被接受。对于 i18n/本地化 PR,请说明工作仅限于本地化;这一常设例外承认了有助于用户在现有翻译系统中使用的语言知识。它不扩展到与翻译捆绑的不相关行为、重构或依赖项。尊重这些边界(包括关闭提交的决定)是贡献的一部分。重新打开被拒绝的 PR 或将其拆分为更小的提交以寻求不同结果,违背了该目的。 改进文档​ 通过改进文档、编写教程或创建安装指南,帮助 Open WebUI 更易用。文档位于 docs 仓库中。 翻译 UI​ 仅限 i18n/本地化的 PR 无需维护者请求。Open WebUI 在 src/lib/i18n/locales 中使用 JSON 翻译文件。每个子目录以 ISO 639 语言代码命名(例如,en-US, fr-FR)。 如果你是 Open WebUI 已支持语言的母语使用者,更正与新翻译一样受欢迎。当你的语言中某个标签读起来不对、不自然或用词错误时,请在该语言的 translation.json 中修复它,并仅包含这些更改发起 PR。 添加新语言: 在 src/lib/i18n/locales 下创建以适当语言代码命名的新目录 将 en-US 翻译文件复制到新目录 翻译每个 JSON 文件中的字符串值,同时保留对象结构 在 src/lib/i18n/locales/languages.json 中注册该语言 改进可访问性​ 可访问性是良好设计的核心组成部分。通过 Issues 报告带有复现详情的可访问性问题。当实施维护者请求的 UI 变更时: 原则 执行动作 语义化 HTML 使用

评论 (0)