企业官网建设流程全解析

• 云原生
• 存储
• 高可用
• 容器编排

Longhorn 是一款构建在 Kubernetes 之上的云原生分布式块存储系统，其贡献并不只局限于代码：报告 Issue、改进文档、评审 PR、测试修复、提出功能建议乃至分享真实部署反馈，都是社区欢迎的贡献形式。本文以仓库根目录的 CONTRIBUTING.md 为骨架，结合本仓库的 README.md、enhancements/、chart/、deploy/、SECURITY.md 等实际内容，系统梳理一条从「发现需求 → 报告 Issue → 撰写增强提案 → 提交 PR → 通过测试与评审 → 合入与 backport」的完整贡献链路，帮助开发者一次性掌握 Longhorn 的协作规范、提交约定与验收标准，直接产出符合项目要求的合格贡献。

为什么需要一份贡献指南：Longhorn 的多仓库协作模型

Longhorn 与单体代码仓库不同，它采用「伞形仓库 + 组件仓库」的组织方式。理解这一点，是读懂整份贡献指南的前提。

当前仓库longhorn是伞形项目（umbrella project），它本身不包含组件源码，而是承担了四类职责：

• Issue 跟踪：所有跨组件的跟踪 Issue 都统一登记在本仓库；
• 增强提案：设计文档存放在 enhancements/ 目录；
• 发布清单：deploy/ 目录存放longhorn.yaml、longhorn-okd.yaml等一体化部署清单与 longhorn-images.txt 镜像清单；
• Helm Chart 源码：chart/ 目录即官方 Chart 的源头，其中 chart/Chart.yaml 当前标注版本为1.12.0-dev、appVersion: v1.12.0-dev，并要求kubeVersion >= 1.34.0-0。

各组件与库的源码则分散在独立仓库中。贡献指南给出了完整的组件对照表，这里完整复述：

在 README.md 的 Components 一节中，这张表还扩展出了库（Library）层面的对应关系：V1 核心逻辑在 longhorn-engine、V2 在 longhorn-spdk-engine，另有 iSCSI Helper、SPDK Helper、Backup Store、Common Libraries 等公共库，并新增了 longhorn/cli 命令行工具。无论代码变更落在哪个组件仓库，跟踪 Issue 一律登记在longhorn/longhorn——这是协作模型的第一条铁律，它保证了任何变更都能回溯到统一的需求来源。

开始之前：开发指南与社区渠道

正式提交代码前，贡献指南要求先阅读社区维护的 Longhorn 开发入门指南（Getting started with Longhorn Development）。此外，Longhorn 提供了丰富的社区交流渠道（见 README.md 的 Community 一节）：

• Discussion / 反馈：可在项目 Discussions 发起讨论；
• Issue / 功能请求：所有 Issue 通过 Issue 选择页提交，项目每周举行社区 Issue 评审会议；
• Bug 报告附带 support bundle：提交 bug 时建议上传 support bundle 到 Issue，或发送至维护组邮箱；
• Slack：CNCF Slack 上的 #longhorn 频道，适合提问与经验交流；
• 月度社区会议：每月第三个周四，交替提供 AMER/EU 友好与 APAC 友好时段；
• 邮件列表：分别订阅开发者（longhorn-dev）与用户（longhorn-users）列表。

对于所有贡献者，项目同时要求先阅读 CODE_OF_CONDUCT.md（行为准则）与 CONTRIBUTING.md（本文）再开始贡献。

报告 Issue：一切 Pull Request 的起点

贡献指南强调：在提交 Pull Request 之前，必须确认存在关联的跟踪 Issue。若不存在，请先创建。

使用正确的 Issue 模板

创建 Issue 时应选用对应的 Issue 模板，以便报告被正确分类并包含必要信息。模板会自动应用匹配的标题前缀，且标题应保留该前缀。指南列出的前缀包括：

• [BUG] <描述>
• [FEATURE] <描述>
• [IMPROVEMENT] <描述>
• [REFACTOR] <描述>
• [DOC] <描述>
• [TEST] <描述>

为什么每个 PR 都要有 Issue

为每个 PR 关联 Issue 能帮助社区：

• 跟踪 bug、增强、回归与设计讨论；
• 理解变更的动机与范围；
• 协调评审、测试、发布规划与 backport 决策；
• 避免重复或冲突的工作。

例外情况：诸如拼写修正之类的小改动可以直接提交；但较大的 bug 修复、行为变更、新功能、重构、依赖升级，以及任何 Chart 相关改动，都必须关联 Issue。

增强提案（LEP）：大变更的前置设计关卡

对于大型功能、架构级改动，或影响存储数据路径、升级行为、公共 API 的变更，指南要求在动手实现之前先提交 Longhorn Enhancement Proposal（LEP）。这是 Longhorn 保证设计质量的核心机制。

提案存放位置与模板

• 提案存放在本仓库的 enhancements/ 目录；
• 以现有提案为模板，将提案以 Pull Request 形式提交用于讨论；
• 尽早达成设计共识，可避免返工，并帮助维护者规划发布与 backport。

从仓库目录可以看到，enhancements 下积累了从 2020 年至今的百余份提案，覆盖卷删除流程、备份存储锁、SPDK 引擎重写、RWX 卷支持、加密卷、v2 引擎热迁移、卷离线重建等关键主题——这本身就是 LEP 机制长期有效运转的直接证据。模板文件 enhancements/YYYYMMDD-template.md 规定了固定结构：

1. Title：简洁描述性标题，文件名全小写并以-替换空格/标点；
2. Summary：至少一个段落的概述，是产出高质量发布说明与路线图的关键；含 Related Issues 链接；
3. Motivation：Goals（成功标准）、Non-goals（明确不做的范围，帮助聚焦讨论）；
4. Proposal：核心提案内容，包含 User Stories、User Experience In Detail、API changes；
5. Design：Implementation Overview、Test plan（引擎增强还需引擎集成测试计划）、Upgrade strategy；
6. Note（可选）。

以较新的提案 enhancements/20260506-global-longhorn-manager.md 为例，可以看到一份合格 LEP 的完整形态：它从 DaemonSet 模型下kube-apiserverwatch 扇出与每 Pod informer 缓存的内存问题出发，明确 Goals（引入 leader-elected 的longhorn-global-managerDeployment）与 Non-goals（本版本不迁移其他 controller、不改变 CSI DaemonSet、不消除 DaemonSet），并给出拓扑示例与 Chart 配置项。这份提案还对应 chart/templates/deployment-global-manager.yaml 与 chart/templates/poddisruptionbudget-global-manager.yaml 等落地模板，是「先提案、后实现、再落地」流程的完整体现。

若不确定变更是否需要提案，可以先开 Issue 询问维护者。

Pull Request 的硬性要求

每个 Pull Request 必须包含：

1. 清晰的变更摘要；
2. 关联 Longhorn Issue 的链接；
3. 变更的动机与上下文；
4. 测试计划与实际测试结果；
5. 已知风险、限制、兼容性顾虑或后续工作。

此外，每次 commit 与 PR 描述都必须引用关联工单号，格式为longhorn/longhorn#1234，使变更能够回溯到跟踪 Issue。PR 应当聚焦、易于评审，避免将无关的修复、重构、格式调整与功能开发混在同一个 PR 中。陈旧 PR 的处理方式见后文「社区贡献分流与陈旧 PR」一节。

测试要求：提供可复现的证据

指南要求每个 PR 在提交前都必须经过测试，并在 PR 描述中说明：测试了什么、如何测试、测试环境、测试结果，以及未运行的测试及原因。

一个推荐的结构化测试环境说明模板如下（原文档完整示例）：

Test environment: - Longhorn version/image: - Kubernetes version: - Kubernetes distribution: - Node count: - OS: - Data engine: - Installation method: Test steps: 1. 2. 3. Result: - PASS / FAIL - Relevant logs, screenshots, or command output if applicable.

根据变更类型，测试可能包括：单元测试、集成测试、端到端测试、升级测试、回归测试、Kubernetes 集群中的手动验证、Helm 安装/升级验证、UI 验证，以及备份、恢复、快照、副本重建、引擎、节点、磁盘、卷生命周期等专项验证。

特别提示：如果 PR 影响存储行为、升级行为、数据路径逻辑、调度、恢复、备份/恢复、快照处理、CSI 行为或 Kubernetes 对象协调（reconciliation），必须提供足够细节供评审者复现测试——这类改动处于数据面核心，评审门槛最高。

提交信息与 PR 标题：遵循 Conventional Commits

PR 标题与 commit 标题都必须遵循 Conventional Commits 规范，格式为：

<type>(optional scope): <description>

常见类型包括：

fix: feat: chore: docs: test: refactor: ci: build: perf:

指南给出的示例：

fix(manager): prevent stale disk ready condition after node recovery feat(engine): add validation for v2 live switchover docs: update snapshot restore troubleshooting guide test(e2e): add regression test for replica rebuild failure chore(deps): update CSI sidecar images

标题应清晰简洁，说明「改了什么」，而不只是「改在哪里」。

DCO 签署：每个提交都必须 sign-off

Longhorn 采用 Developer Certificate of Origin（DCO）机制。通过签署提交，你证明自己有权在项目许可证下提交该贡献。创建提交时使用--signoff（或-s）选项：

git commit -s -m "fix(manager): handle replica cleanup error"

这会在提交信息中追加一行：

Signed-off-by: Your Name <your-email@example.com>

PR 中的每个提交都必须包含有效的 sign-off。若已创建的提交未签署，可以修正或 rebase：

git commit --amend --signoff

或多个提交时：

git rebase --signoff <base-branch>

编码规范：Go import 分组约定

Go 代码必须遵循 Longhorn 编码约定，其中特别强调import 分组必须与既有代码库保持一致，并用空行分隔。期望的分组顺序一般为：

1. Go 标准库包；
2. 第三方包；
3. Kubernetes 相关包；
4. 当前仓库之外的 Longhorn 组件包；
5. 当前仓库内的包。

使用别名时，应与邻近 import 及 Longhorn 既有代码模式保持分组一致。提交 PR 前，请先运行所改仓库对应的格式化与校验命令。

Chart 变更：应该提交到哪里

这是 Longhorn 独有的重要规则：不要直接向 charts 发布仓库提交 PR。longhorn/charts仓库仅用于发布已发布的 Helm Chart。Chart 变更应提交到源仓库（即longhorn/longhorn本仓库）。

Chart 变更合入并准备发布后，会通过发布流程同步到 charts 发布仓库。从本仓库可看到这套流程的落地痕迹：chart/ 下有完整的 templates（含 deployment-global-manager.yaml、poddisruptionbudget-global-manager.yaml、network-policies/ 等）、values.yaml 与 Chart.yaml；scripts/ 目录则提供了配套的生成与同步工具，如 scripts/generate-longhorn-yaml.sh（生成部署清单）、scripts/helm-docs.sh（生成 Chart 文档）、scripts/update-chart-values.sh 与 scripts/update-chart-questions.sh 等，印证了「Chart 源码在伞形仓库、发布产物由其派生」的工作流。

文档变更：两份仓库的分工

Longhorn 的官方产品文档（发布于 longhorn.io）维护在独立网站仓库中，安装、配置、运维、故障排查、升级与功能文档的变更都应提交到那里。

而仓库级文档——如 README、开发说明、Helm Chart 文档、示例与设计文档——则应更新到拥有该内容的仓库。一个变更可能同时需要在组件仓库和网站仓库提交文档 PR。

文档 PR 需要满足：

• 内容准确，与当前 Longhorn 行为一致；
• 当变更影响用户可见行为、故障排查、安装、升级、设置或功能文档时，关联longhorn/longhorn的 Issue；
• 更新正确的文档版本，且若其他受支持版本同样适用，需同步应用；
• 措辞清晰简洁；
• 示例、命令与 YAML 片段均已实测。

Backport 与发布分支

Longhorn 在master之外维护多个发布分支（例如v1.x.x）：

• 新功能通常先合入master；
• 影响已发布版本的修复会被 backport 到相应发布分支；backport 的 Issue 与 PR 使用[BACKPORT]前缀并标注目标版本；
• 报告或修复 bug 时，请说明受影响的已发布版本，便于维护者规划 backport。

从本仓库可以直接看到当前的发布分支现状：support-versions.txt 列出了正在积极支持的版本v1.11.3与v1.12.1；README.md 的 Release 表进一步展示了完整生命周期——1.12、1.11处于 Active 状态，1.10至1.1均已有明确的最新版本与稳定版本记录。发布分支策略直接决定了你的修复「该提交到哪个分支」。

评审流程与评审者关注点

维护者与评审者在评审中可能会要求：

• 更多测试覆盖；
• 额外的手动验证；
• 设计澄清；
• 向后兼容性分析；
• 升级或回滚考量；
• 文档更新；
• 更小、更聚焦的 PR。

请保持讨论的建设性与技术性。评审意见是正常贡献流程的一部分，是保证 Longhorn 质量的关键环节。

社区贡献分流与陈旧 PR 处理

长时间无有效活动的 PR 可能被标记为 stale。关闭陈旧 PR 之前，Longhorn 成员应判断该变更对项目是否仍有价值：

• 若贡献者仍有意继续，则按常规继续评审；
• 若无回应但 PR 仍有价值，Longhorn 成员可以接手该工作，并保留原贡献者的署名——例如在适当时保留作者身份，或在最终提交中使用Co-authored-bytrailer。

指南给出了完整的陈旧 PR 处理流程：

安全问题：走私密上报通道

不要在 GitHub Issue 或 PR 中公开披露安全漏洞，应通过项目安全流程上报。本仓库的 SECURITY.md 给出了完整的补充要求，值得贡献者一并阅读：

• 上报前确认漏洞影响的是受支持版本；
• 只上报有潜在安全影响的 bug；CVE 扫描器发现并已公开的 CVE、安全加固指南的改进建议、与安全无关的 bug（应走普通 Issue）、镜像问题等不在该通道范围内；
• 上报信息须视为禁运（embargoed）信息，不得公开分享，直到修复发布；
• 上报需提供：出现问题的产品名与版本、问题描述、漏洞类型与影响、复现步骤、有效的 POC（在获得授权的系统上）、以及是否使用 AI 工具及其模型的强制声明。

提交前最终 Checklist

在请求评审之前，请逐项确认（以下为原文档完整清单）：

• 在 Longhorn Issue 跟踪器中存在关联 Issue；
• 代码 PR 指向正确的组件仓库；
• PR 描述说明了动机与范围；
• commit 与 PR 描述引用了关联工单号（如longhorn/longhorn#1234）；
• PR 标题遵循 Conventional Commits；
• 每个 commit 标题遵循 Conventional Commits；
• 每个 commit 都包含有效的 DCO sign-off；
• 变更已经过测试；
• 测试步骤与结果已写入 PR 描述；
• Go import 遵循 Longhorn 编码约定；
• 必要时已在合适的仓库更新文档；
• Chart 变更提交到longhorn/longhorn，而非 charts 发布仓库；
• 已考虑对受支持发布分支的 backport；
• PR 只包含相关变更。

对照这份清单走完流程，你的贡献就具备了进入 Longhorn 评审与发布管线的基本条件。无论是第一行代码还是第一份 LEP，社区都欢迎你加入——正如 CONTRIBUTING.md 结尾所言：感谢你帮助改进 Longhorn。

• 云原生
• 存储
• 高可用
• 容器编排