Headlamp 贡献指南从 Issue 到 PR 的完整工作流——测试、Lint、提交规范与 CI 验证详解【免费下载链接】headlampA Kubernetes web UI that is fully-featured, user-friendly and extensible项目地址: https://gitcode.com/GitHub_Trending/he/headlamp本文基于 Headlamp 仓库的官方贡献文档docs/contributing.md展开系统讲解向该项目提交代码的完整流程如何提交规范的 Issue、如何编写符合area: description格式的原子化提交、如何撰写可被快速评审的 PR 描述以及如何通过前后端 Lint 与测试套件。读完本文你可以独立跑通 Headlamp 的本地验证命令并理解其 CI 在 PR 合并前实际执行了哪些检查。贡献环境仓库结构与前置假设Headlamp 的贡献文档假设你已克隆了该仓库或自己的 fork并且所有贡献均受项目 Apache 2.0 许可协议约束协议全文见 LICENSE。从源码结构看Headlamp 是一个多包 Monorepo贡献工作主要集中在以下几个目录这与贡献文档中反复出现的backend:/frontend:提交前缀直接对应frontend/React Vite 实现的 Web UI 主体使用 TypeScript、Redux Toolkit、React Querybackend/Go 编写的服务端负责 K8s API 代理、认证、Helm 集成等app/Electron 桌面应用封装层plugins/插件体系与示例插件。开发环境有明确的版本要求根目录 package.json 的engines字段声明需要node 22.6.0和npm 11.0.0frontend/package.json 要求node 22.0.0。建议在动手前确认本地版本满足这一前提。此外项目遵循 Kinvolk 的贡献指南以促进跨项目一致且良好的贡献实践项目还每月举行一次社区会议Community Monthly Call讨论项目与路线图该事件在 CNCF 日历上可查原文档外链地址此处不再重复。提交 Issue 与功能请求先搜索再提交贡献文档明确要求提交前先用 issue tracker 搜索是否已存在相同问题若已存在向已有 Issue 补充信息比新建 Issue 更高效。若问题不存在则使用仓库内置的两种模板之一创建新 IssueBug 报告模板.github/ISSUE_TEMPLATE/bug_report.md功能请求模板.github/ISSUE_TEMPLATE/feature_request.md从 Bug 模板的实际内容看一个合格的 Bug 报告需要覆盖五个部分问题描述包含期望结果、复现步骤逐步操作、环境信息安装类型如 Linux-Flatpak / Windows-Chocolatey / Mac-Homebrew / Container-Image / In-Cluster / Helm 等以及 Headlamp 版本号、是否能自行修复Yes/No以及附加上下文截图、是否回归、哪个版本尚未出现该问题。模板结尾还直接引用了贡献文档与 Slack 频道引导有能力修复的贡献者进入贡献流程。安全漏洞单独渠道对于敏感、不宜公开的漏洞类安全问题贡献文档要求走安全渠道而非公开 issue tracker具体流程见仓库根目录的 SECURITY.md。提交 Pull Request 的四步规范第一步运行测试并格式化代码贡献文档要求从项目根目录执行以下命令确保代码功能正确、类型安全、格式一致# 运行前端测试套件 npm run frontend:test # 格式化/检查前端代码 npm run frontend:lint结合根目录 package.json 的脚本定义可以确认这两条命令的实际行为frontend:test展开为cd frontend npm test -- --coverage即前端使用 Vitest 运行测试并附带覆盖率统计frontend:lint展开为cd frontend npm run lint -- --max-warnings 0 npm run format-check即 ESLint 以--max-warnings 0零警告容忍运行后再用 Prettier 做格式检查。完整的 lint 与测试矩阵还包括后端与桌面应用Makefile 中提供了对应的 Make 目标与 npm 脚本一一对应命令Make 目标实际执行npm run backend:lintmake backend-lint安装 golangci-lint v2.12.2 后在backend/下执行./tools/golangci-lint runnpm run backend:testmake backend-testcd backend go test -v -p 1 ./...npm run frontend:lintmake frontend-lintESLint Prettierformat-checknpm run frontend:testmake frontend-testcd frontend npm run test -- --coverage一个值得注意的细节backend:lint并不是调用全局安装的 golangci-lint而是通过backend:install:linter把指定版本v2.12.2安装到backend/tools/目录中再运行从而保证本地与 CI 的 lint 行为一致。若只修改了前端代码npm run lint:fix/make lint-fix可以自动修复 ESLint 与 Prettier 可修复的问题。第二步遵循提交Commit指南贡献文档要求使用原子提交atomic commits——每个提交只聚焦一个逻辑变更并按如下结构书写提交信息area: description of changes核心规则逐条继承自原文档长度限制提交标题第一行与正文每一行均不得超过 72 个字符正文按 72 字符换行。原子性与自包含逻辑上独立的变更必须拆分到不同提交这一原则的出处是 Linux Kernel 的补丁提交指南separate your changes 一节。解释动机提交正文应说明为什么做这个变更why而标题负责说明做了什么what。不要引入将被后续提交修改的代码那会让中间提交的评审失去意义也不要为遗漏代码补提交应使用 squash 合并相关提交。不保留开发历史贡献变更时应使用git rebase压缩、重排提交只保留最终结构良好的提交序列而不是展示走向最终状态的完整开发史。自查后再开 PR批判性地审阅自己的改动能提前发现错误、节省评审者与自己的时间。PR 描述当封面信用说明为何提出该变更、给出概览、列出尚未解决的疑问与 TODO 项。原文档给出的正反示例好的提交标题frontend: HomeButton: Fix so it navigates to homebackend: config: Add enable-dynamic-clusters flag坏的提交标题updates the manifest无区域前缀、无动因Init feature added.信息量不足this adds new colors to the dashboard无区域前缀、口语化第三步撰写有信息量的 PR 描述打开 PR 时必须做到三点概括变更内容与动机what 与 why关联相关 Issue使用fixes #ISSUE_NUMBER语法提供测试步骤Steps to Test。仓库内置的 PR 模板.github/pull_request_template.md正是上述要求的落地形式它固定了六个小节Summary一句话概括 adds/fixes 了什么、Related IssueFixes #ISSUE_NUMBER、Changes新增/修复/重构清单、Steps to Test编号步骤、Screenshots (if applicable)、Notes for the Reviewer给评审者的特别提示例如本次改动涉及 i18n 层请检查语言一致性。贡献文档中的示例描述可对照该模板填写This PR fixes the home button bug where the button did not navigate back to the homepage.Steps to Test:Click on the Home button in the sidebar.Verify that it navigates to the main screen.第四步使用标签Labels组织 PR为 PR 添加相关标签有助于分诊triage与优先级排序原文档给出的示例标签包括enhancement、documentation等。Bug 模板中也可以看到标签的自动应用机制使用 bug 模板创建 Issue 时会自动带上kind/bug标签见 bug_report.md 的 frontmatter。编码风格与 Lint 门禁贡献文档强调backend与frontend的代码风格必须保持一致项目为此配备了 Go 与 JS 两套 linter本地验证命令分别为# 后端 Go 代码 lint npm run backend:lint # 前端 JS/TS 代码 lint npm run frontend:lint这两条命令同样在 CI 中运行——从 .github/workflows/frontend.yml 可以看到前端相关路径变更触发的工作流包含多个 joblint安装依赖后执行cd frontend npm run ci-lint其中ci-lint定义于 frontend/package.json使用独立的.eslintrc.ci.cjs配置带--max-warnings 0并追加 Prettierformat-checktest执行make frontend-testVitest 全量测试随后运行make frontend-i18n-check即npm run i18n -- --fail-on-update校验 i18n 资源文件是否已随代码同步更新build执行make frontend-build与make frontend-build-rsbuild同时验证 Vite 与 rsbuild 两条构建链路可用。因此贡献文档特别提醒为加快维护者评审务必保证 PR 的 CI 检查全部通过后再请求 review。另外从 frontend/package.json 可以看到项目配置了 husky lint-staged 的 pre-commit 钩子提交前会自动对暂存的src/**、../app/**、../plugins/headlamp-plugin/**、../plugins/examples/**、../e2e-tests/**下文件执行eslint --fix与prettier --write即格式问题在本地提交时就被拦截的设计。复杂变更先讨论再动手对于复杂贡献——即涉及架构调整或大量代码行变更——贡献文档建议的路线是先在 GitHub issue tracker 提交一个 Issue 描述方案通过 Kubernetes Slack 的#headlamp频道与维护者讨论实现方式确认方向后再开 PR。这条规则的目的同样体现在 CI 设计上大型架构变更若未经讨论直接提交大概率与frontend.yml、backend-test.yml等工作流所守护的约定依赖版本、lint 规则、构建链路冲突返工成本远高于前期沟通。翻译贡献i18n希望为 Headlamp 做国际化的贡献者应遵循专门的多语言文档 docs/development/i18n/index.md。该文档说明 Headlamp 的 i18n 基于i18next i18next-parser react-i18next实现并给出两个关键机制浏览器语言检测使用 i18next-browser-languagedetector可通过 cookie、html 语言标签等方式选择语言也可在 URL 中使用?lngen强制切换语言语言包按需加载语言文件位于src/i18n/locales/{{lng}}/{{ns}}.json{{lng}}为语言代码、{{ns}}为命名空间通过动态导入实现代码分割、按需加载。仓库提供了配套的翻译维护命令见根目录 package.json# 更新 frontend 与 app 的 i18n 资源 npm run i18n # CI 风格的严格检查资源文件如有落后即失败 npm run i18n:check这也解释了为何前端 CI 中专门有frontend-i18n-check一步翻译资源与代码必须同步提交。测试体系前端快照 后端 Go 测试贡献文档的 Testing 章节给出了项目测试策略的全貌前端测试围绕 Storybook 相关快照进行因此新组件在可能的情况下必须附带对应的 story。运行命令npm run frontend:test从仓库结构可以印证这一策略前端各组件目录下普遍存在.storyshot快照文件例如 frontend/src/components/pod/、frontend/src/components/common/ 下都有大量快照测试框架为 Vitesttest: vitest定义于 frontend/package.json。此外 frontend/package.json 还提供test:a11y构建 Storybook 后运行test-a11y-with-baseline.mjs用于可访问性基线校验。后端使用 Go 原生测试框架运行命令npm run backend:test展开为cd backend go test -v -p 1 ./...-p 1保证包串行执行避免测试间资源竞争。Makefile 中还提供了进一步的能力供贡献者使用make backend-coverage生成覆盖率报告并按函数输出go tool cover -funcmake backend-fuzz对pkg/auth、pkg/kubeconfig、pkg/clusterinventory中的指定入口运行模糊测试make backend-format对cmd/与pkg/执行go fmt。最后所有测试都会在 PR 打开后作为 CI 的一部分自动运行——这意味着本地测试全绿 lint 全绿是 PR 进入人工评审的最低门槛与贡献文档make sure that the CI checks are passing for your PR的要求形成闭环。小结Headlamp 的贡献流程可以浓缩为一条链路搜索/提交规范 Issue → 本地跑backend:lint、frontend:lint、frontend:test、backend:test全绿 → 按area: description格式用git rebase整理出原子提交 → 用内置 PR 模板撰写含fixes #ISSUE与测试步骤的描述 → 打标签 → 确认 CI 通过后请求评审。对于架构级变更先走 Issue Slack 讨论对于翻译贡献走 i18n 文档与npm run i18n工作流。所有规则都能在仓库中找到落地物证npm 脚本与 Make 目标package.json、Makefile、Issue/PR 模板.github/ISSUE_TEMPLATE/、.github/pull_request_template.md、CI 工作流.github/workflows/贡献者可据此自行复核每一项检查的具体行为。【免费下载链接】headlampA Kubernetes web UI that is fully-featured, user-friendly and extensible项目地址: https://gitcode.com/GitHub_Trending/he/headlamp创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 Headlamp 贡献指南：从 Issue 到 PR 的完整工作流——测试、Lint、提交规范与 CI 验证详解
Headlamp 贡献指南从 Issue 到 PR 的完整工作流——测试、Lint、提交规范与 CI 验证详解【免费下载链接】headlampA Kubernetes web UI that is fully-featured, user-friendly and extensible项目地址: https://gitcode.com/GitHub_Trending/he/headlamp本文基于 Headlamp 仓库的官方贡献文档docs/contributing.md展开系统讲解向该项目提交代码的完整流程如何提交规范的 Issue、如何编写符合area: description格式的原子化提交、如何撰写可被快速评审的 PR 描述以及如何通过前后端 Lint 与测试套件。读完本文你可以独立跑通 Headlamp 的本地验证命令并理解其 CI 在 PR 合并前实际执行了哪些检查。贡献环境仓库结构与前置假设Headlamp 的贡献文档假设你已克隆了该仓库或自己的 fork并且所有贡献均受项目 Apache 2.0 许可协议约束协议全文见 LICENSE。从源码结构看Headlamp 是一个多包 Monorepo贡献工作主要集中在以下几个目录这与贡献文档中反复出现的backend:/frontend:提交前缀直接对应frontend/React Vite 实现的 Web UI 主体使用 TypeScript、Redux Toolkit、React Querybackend/Go 编写的服务端负责 K8s API 代理、认证、Helm 集成等app/Electron 桌面应用封装层plugins/插件体系与示例插件。开发环境有明确的版本要求根目录 package.json 的engines字段声明需要node 22.6.0和npm 11.0.0frontend/package.json 要求node 22.0.0。建议在动手前确认本地版本满足这一前提。此外项目遵循 Kinvolk 的贡献指南以促进跨项目一致且良好的贡献实践项目还每月举行一次社区会议Community Monthly Call讨论项目与路线图该事件在 CNCF 日历上可查原文档外链地址此处不再重复。提交 Issue 与功能请求先搜索再提交贡献文档明确要求提交前先用 issue tracker 搜索是否已存在相同问题若已存在向已有 Issue 补充信息比新建 Issue 更高效。若问题不存在则使用仓库内置的两种模板之一创建新 IssueBug 报告模板.github/ISSUE_TEMPLATE/bug_report.md功能请求模板.github/ISSUE_TEMPLATE/feature_request.md从 Bug 模板的实际内容看一个合格的 Bug 报告需要覆盖五个部分问题描述包含期望结果、复现步骤逐步操作、环境信息安装类型如 Linux-Flatpak / Windows-Chocolatey / Mac-Homebrew / Container-Image / In-Cluster / Helm 等以及 Headlamp 版本号、是否能自行修复Yes/No以及附加上下文截图、是否回归、哪个版本尚未出现该问题。模板结尾还直接引用了贡献文档与 Slack 频道引导有能力修复的贡献者进入贡献流程。安全漏洞单独渠道对于敏感、不宜公开的漏洞类安全问题贡献文档要求走安全渠道而非公开 issue tracker具体流程见仓库根目录的 SECURITY.md。提交 Pull Request 的四步规范第一步运行测试并格式化代码贡献文档要求从项目根目录执行以下命令确保代码功能正确、类型安全、格式一致# 运行前端测试套件 npm run frontend:test # 格式化/检查前端代码 npm run frontend:lint结合根目录 package.json 的脚本定义可以确认这两条命令的实际行为frontend:test展开为cd frontend npm test -- --coverage即前端使用 Vitest 运行测试并附带覆盖率统计frontend:lint展开为cd frontend npm run lint -- --max-warnings 0 npm run format-check即 ESLint 以--max-warnings 0零警告容忍运行后再用 Prettier 做格式检查。完整的 lint 与测试矩阵还包括后端与桌面应用Makefile 中提供了对应的 Make 目标与 npm 脚本一一对应命令Make 目标实际执行npm run backend:lintmake backend-lint安装 golangci-lint v2.12.2 后在backend/下执行./tools/golangci-lint runnpm run backend:testmake backend-testcd backend go test -v -p 1 ./...npm run frontend:lintmake frontend-lintESLint Prettierformat-checknpm run frontend:testmake frontend-testcd frontend npm run test -- --coverage一个值得注意的细节backend:lint并不是调用全局安装的 golangci-lint而是通过backend:install:linter把指定版本v2.12.2安装到backend/tools/目录中再运行从而保证本地与 CI 的 lint 行为一致。若只修改了前端代码npm run lint:fix/make lint-fix可以自动修复 ESLint 与 Prettier 可修复的问题。第二步遵循提交Commit指南贡献文档要求使用原子提交atomic commits——每个提交只聚焦一个逻辑变更并按如下结构书写提交信息area: description of changes核心规则逐条继承自原文档长度限制提交标题第一行与正文每一行均不得超过 72 个字符正文按 72 字符换行。原子性与自包含逻辑上独立的变更必须拆分到不同提交这一原则的出处是 Linux Kernel 的补丁提交指南separate your changes 一节。解释动机提交正文应说明为什么做这个变更why而标题负责说明做了什么what。不要引入将被后续提交修改的代码那会让中间提交的评审失去意义也不要为遗漏代码补提交应使用 squash 合并相关提交。不保留开发历史贡献变更时应使用git rebase压缩、重排提交只保留最终结构良好的提交序列而不是展示走向最终状态的完整开发史。自查后再开 PR批判性地审阅自己的改动能提前发现错误、节省评审者与自己的时间。PR 描述当封面信用说明为何提出该变更、给出概览、列出尚未解决的疑问与 TODO 项。原文档给出的正反示例好的提交标题frontend: HomeButton: Fix so it navigates to homebackend: config: Add enable-dynamic-clusters flag坏的提交标题updates the manifest无区域前缀、无动因Init feature added.信息量不足this adds new colors to the dashboard无区域前缀、口语化第三步撰写有信息量的 PR 描述打开 PR 时必须做到三点概括变更内容与动机what 与 why关联相关 Issue使用fixes #ISSUE_NUMBER语法提供测试步骤Steps to Test。仓库内置的 PR 模板.github/pull_request_template.md正是上述要求的落地形式它固定了六个小节Summary一句话概括 adds/fixes 了什么、Related IssueFixes #ISSUE_NUMBER、Changes新增/修复/重构清单、Steps to Test编号步骤、Screenshots (if applicable)、Notes for the Reviewer给评审者的特别提示例如本次改动涉及 i18n 层请检查语言一致性。贡献文档中的示例描述可对照该模板填写This PR fixes the home button bug where the button did not navigate back to the homepage.Steps to Test:Click on the Home button in the sidebar.Verify that it navigates to the main screen.第四步使用标签Labels组织 PR为 PR 添加相关标签有助于分诊triage与优先级排序原文档给出的示例标签包括enhancement、documentation等。Bug 模板中也可以看到标签的自动应用机制使用 bug 模板创建 Issue 时会自动带上kind/bug标签见 bug_report.md 的 frontmatter。编码风格与 Lint 门禁贡献文档强调backend与frontend的代码风格必须保持一致项目为此配备了 Go 与 JS 两套 linter本地验证命令分别为# 后端 Go 代码 lint npm run backend:lint # 前端 JS/TS 代码 lint npm run frontend:lint这两条命令同样在 CI 中运行——从 .github/workflows/frontend.yml 可以看到前端相关路径变更触发的工作流包含多个 joblint安装依赖后执行cd frontend npm run ci-lint其中ci-lint定义于 frontend/package.json使用独立的.eslintrc.ci.cjs配置带--max-warnings 0并追加 Prettierformat-checktest执行make frontend-testVitest 全量测试随后运行make frontend-i18n-check即npm run i18n -- --fail-on-update校验 i18n 资源文件是否已随代码同步更新build执行make frontend-build与make frontend-build-rsbuild同时验证 Vite 与 rsbuild 两条构建链路可用。因此贡献文档特别提醒为加快维护者评审务必保证 PR 的 CI 检查全部通过后再请求 review。另外从 frontend/package.json 可以看到项目配置了 husky lint-staged 的 pre-commit 钩子提交前会自动对暂存的src/**、../app/**、../plugins/headlamp-plugin/**、../plugins/examples/**、../e2e-tests/**下文件执行eslint --fix与prettier --write即格式问题在本地提交时就被拦截的设计。复杂变更先讨论再动手对于复杂贡献——即涉及架构调整或大量代码行变更——贡献文档建议的路线是先在 GitHub issue tracker 提交一个 Issue 描述方案通过 Kubernetes Slack 的#headlamp频道与维护者讨论实现方式确认方向后再开 PR。这条规则的目的同样体现在 CI 设计上大型架构变更若未经讨论直接提交大概率与frontend.yml、backend-test.yml等工作流所守护的约定依赖版本、lint 规则、构建链路冲突返工成本远高于前期沟通。翻译贡献i18n希望为 Headlamp 做国际化的贡献者应遵循专门的多语言文档 docs/development/i18n/index.md。该文档说明 Headlamp 的 i18n 基于i18next i18next-parser react-i18next实现并给出两个关键机制浏览器语言检测使用 i18next-browser-languagedetector可通过 cookie、html 语言标签等方式选择语言也可在 URL 中使用?lngen强制切换语言语言包按需加载语言文件位于src/i18n/locales/{{lng}}/{{ns}}.json{{lng}}为语言代码、{{ns}}为命名空间通过动态导入实现代码分割、按需加载。仓库提供了配套的翻译维护命令见根目录 package.json# 更新 frontend 与 app 的 i18n 资源 npm run i18n # CI 风格的严格检查资源文件如有落后即失败 npm run i18n:check这也解释了为何前端 CI 中专门有frontend-i18n-check一步翻译资源与代码必须同步提交。测试体系前端快照 后端 Go 测试贡献文档的 Testing 章节给出了项目测试策略的全貌前端测试围绕 Storybook 相关快照进行因此新组件在可能的情况下必须附带对应的 story。运行命令npm run frontend:test从仓库结构可以印证这一策略前端各组件目录下普遍存在.storyshot快照文件例如 frontend/src/components/pod/、frontend/src/components/common/ 下都有大量快照测试框架为 Vitesttest: vitest定义于 frontend/package.json。此外 frontend/package.json 还提供test:a11y构建 Storybook 后运行test-a11y-with-baseline.mjs用于可访问性基线校验。后端使用 Go 原生测试框架运行命令npm run backend:test展开为cd backend go test -v -p 1 ./...-p 1保证包串行执行避免测试间资源竞争。Makefile 中还提供了进一步的能力供贡献者使用make backend-coverage生成覆盖率报告并按函数输出go tool cover -funcmake backend-fuzz对pkg/auth、pkg/kubeconfig、pkg/clusterinventory中的指定入口运行模糊测试make backend-format对cmd/与pkg/执行go fmt。最后所有测试都会在 PR 打开后作为 CI 的一部分自动运行——这意味着本地测试全绿 lint 全绿是 PR 进入人工评审的最低门槛与贡献文档make sure that the CI checks are passing for your PR的要求形成闭环。小结Headlamp 的贡献流程可以浓缩为一条链路搜索/提交规范 Issue → 本地跑backend:lint、frontend:lint、frontend:test、backend:test全绿 → 按area: description格式用git rebase整理出原子提交 → 用内置 PR 模板撰写含fixes #ISSUE与测试步骤的描述 → 打标签 → 确认 CI 通过后请求评审。对于架构级变更先走 Issue Slack 讨论对于翻译贡献走 i18n 文档与npm run i18n工作流。所有规则都能在仓库中找到落地物证npm 脚本与 Make 目标package.json、Makefile、Issue/PR 模板.github/ISSUE_TEMPLATE/、.github/pull_request_template.md、CI 工作流.github/workflows/贡献者可据此自行复核每一项检查的具体行为。【免费下载链接】headlampA Kubernetes web UI that is fully-featured, user-friendly and extensible项目地址: https://gitcode.com/GitHub_Trending/he/headlamp创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考