Focalboard 贡献者 PR 提交检查清单：从 CLA 签署到代码合入的完整流程

导读

本文以 Focalboard 仓库的贡献文档 docs/contribution-checklist.md 为主线，完整梳理社区开发者向该开源项目提交 Pull Request（PR）前必须逐项核对的操作清单，并结合仓库内的 CI 配置、测试体系、本地化工具链与代码审查流程，说明每一条检查项背后的真实工程约束。读完本文，你将能理解 Focalboard（以及同类 Mattermost 系开源项目）的合入门槛，掌握 npm run i18n-extract 等关键命令的用法，并清楚 PR 从创建、通过自动化构建到完成代码审查的完整生命周期。

Focalboard 是一个开源、可自托管的项目管理与看板工具，通常被用作 Trello、Notion、Asana 的替代方案。其代码库包含 Go 编写的服务端（server/）、TypeScript/React 编写的 Web 前端（webapp/），以及 mac、win-wpf、linux 等多个桌面端实现。社区贡献者的代码要合入 main 分支，需要经过贡献检查清单、自动化构建、代码审查三道关卡，本文逐一拆解。

一、提交 PR 前的六步检查清单

贡献检查清单 明确列出了社区开发者提交 PR 前需要逐项确认的六条硬性要求。下面逐条展开，并结合仓库实际文件说明每一条的含义。

1. 签署贡献者许可协议（CLA）

第一条要求是签署 Mattermost 的 Contributor License Agreement（CLA），以便被添加进 Mattermost 的 Approved Contributor List（已批准贡献者名单）。这是整个贡献流程的法律前提，它明确了代码版权的归属与授权方式，只有签署过 CLA 的贡献者，其提交的代码才能被合法合入上游仓库。签署情况会由维护者在后台核对，属于 PR 合入的硬性门槛。

2. 工作项必须是 Help Wanted 类型的 GitHub Issue

第二条要求你的工作项对应的是目标项目上的 Help Wanted GitHub Issue。这类 Issue 由维护团队明确标记，表示该任务已得到官方认可、适合外部开发者认领，从而保证外部贡献与项目整体方向一致。

• 如果你的改动没有对应的 Help Wanted 票，则需要走"无票贡献"流程，详见 docs/contributions-without-ticket.md。
• 该文档指出：少于 20 行代码的缺陷修复或增量改进，通常无需开票即可被接受；而超过 20 行的改动，核心团队应先行开立 Help Wanted 票，以统一项目愿景。
• 即使是无票提交，PR 也会先由核心团队的产品经理审查；如果核心提交者认为改动显著改变了行为或用户预期，仍有权拒绝合入。
• 与核心团队讨论开票事宜，可以在 Contributors 频道发起对话，或在仓库 Issues 页面新建 Issue。

3. 代码必须经过充分测试

第三条要求代码经过充分测试，包括适当的单元测试和手工测试。Focalboard 的测试体系在仓库中非常完整，可以从源码和配置中直接验证：

• Web 前端：使用 Jest 运行单元测试，配置见 webapp/package.json 中的 test 脚本（jest）。仓库内大量组件、工具函数与 reducer 均配有同名 .test.ts / .test.tsx 文件，例如 webapp/src/mutator.test.ts、webapp/src/cardFilter.test.ts、webapp/src/utils.test.ts 等；Jest 配置还开启了覆盖率收集（collectCoverage: true）。
• 端到端测试：使用 Cypress，测试用例位于 webapp/cypress/integration，覆盖建板、卡片徽章、分组、登录等关键路径（如 createBoard.ts、cardBadges.ts、groupByProperty.ts、loginActions.ts）。
• 服务端：Go 单元测试覆盖 server/app、server/services 等目录，例如 server/app/app_test.go、server/app/blocks_test.go；存储层还通过 server/services/store/storetests 对 sqlite、mysql、mariadb、postgres 四种数据库做一致性验证。

在提交 PR 前，建议先在本地跑通与 CI 相同的检查命令，再提交。具体命令见下文"自动化构建"一节。

4. 用户界面字符串必须进入本地化文件（en.json）

第四条针对包含用户界面文本的改动：UI 字符串需要写入本地化文件，即 webapp/i18n/en.json。然后在 webapp 目录下运行：

npm run i18n-extract

这条命令用于生成/更新英文翻译字符串，其底层实现定义在 webapp/package.json 的 i18n-extract 脚本中：

"i18n-extract": "formatjs extract \"src/**/*.{ts,tsx}\" --ignore \"**/*.d.ts\" \"../**/*.d.ts\" --out-file i18n/tmp.json && formatjs compile i18n/tmp.json --out-file i18n/en.json && npx rimraf i18n/tmp.json"

它使用 @formatjs/cli（见 devDependencies）完成两步工作：先扫描 src/**/*.{ts,tsx} 提取所有翻译 key 生成临时文件，再用 formatjs compile 编译输出到 i18n/en.json，最后清理临时文件。仓库中的 webapp/i18n/en.json 采用"模块名.描述"的扁平 key 结构（如 AttachmentBlock.addElement、BoardComponent.new），并在 webapp/i18n 目录下同步维护了 37 种语言文件（zh_Hans.json、ja.json、de.json 等）。

在代码中使用翻译文案的典型方式是 React Intl 的 useIntl() 钩子，例如 webapp/src/components/addContentMenuItem.tsx 中的 const intl = useIntl()，以及 webapp/src/components/boardTemplateSelector/boardTemplateSelector.tsx 等大量组件。因此，任何新增或修改的 UI 文本都应通过 intl.formatMessage / FormattedMessage 引用，并同步执行 npm run i18n-extract 更新 en.json，而不是硬编码字符串。

5. PR 必须从你的 Fork 提交到 main 分支

第五条是分支与仓库要求：PR 必须从你的 Fork 提交，目标分支为 main。这一约定保证了合入历史清晰、review 与 rebase 可控。根目录 Makefile 与 CI 工作流也均以 main 为基准分支，例如 .github/workflows/ci.yml 中 push 触发器明确监听 main 与 releases-** 分支。

6. PR 标题必须以 GitHub Ticket ID 开头，并填写摘要模板

第六条是格式要求：

• PR 标题以 GitHub Ticket ID 开头，例如 [GH-394]；
• 填写仓库提供的 PR 摘要模板。

仓库根目录的 pull_request_template.md 就是该模板，其结构包含：

• #### Summary：描述 PR 做了什么，以及 QA 测试步骤（如果适用且未写入 ticket）；
• #### Ticket Link：关联 GitHub Issue（如 Fixes https://github.com/mattermost/focalboard/issues/XXXXX）或 JIRA 票；
• 模板注释中还建议为 PR 指派两位 reviewer（如不确定，可设置 Core Focalboard 为 reviewer），并要求先阅读贡献检查清单与《Submitting Great PRs》一文。

二、提交后：自动化构建必须通过

检查清单最后一段明确了合入前提：提交后，自动化构建（automated build process）必须通过，PR 才能被接受；任何错误或失败都需要先解决。

Focalboard 的自动化检查在 .github/workflows/ci.yml 中定义，名为 "Check-in tests"，由三组并行任务构成：

• ci-ubuntu-server：在 ubuntu-22.04 上对 sqlite、mysql、mariadb、postgres 四种数据库分别执行 make server-test-<db>，覆盖服务端全套单元测试；
• ci-ubuntu-webapp：先构建 Linux 服务器（make server-linux-package），再将服务器二进制复制给 Cypress 使用，最后执行 make webapp-ci，即依次运行 lint、单元测试与 Cypress 端到端测试；
• ci-windows-server / ci-mac-server：在 Windows 2022 与 macOS 上运行 make server-test-mini-sqlite，验证跨平台兼容性。

其中 make webapp-ci 对应的命令在根 Makefile 中定义：

webapp-ci: ## Webapp CI: linting & testing.
	cd webapp; npm run check
	cd webapp; npm run test
	cd webapp; npm run cypress:ci

而 npm run check 在 webapp/package.json 中定义为 ESLint（eslint --ext .tsx,.ts . --quiet --cache）加 Stylelint（stylelint **/*.scss）的静态检查；cypress:ci 则通过 start-server-and-test 先启动服务器（runserver-test，即运行编译出的 bin/focalboard-server），再等待 http://localhost:8088 就绪后执行 cypress run。此外还有独立的 .github/workflows/lint-server.yml 负责服务端 golangci-lint 检查（对应 make server-lint）。

因此，贡献者在提交 PR 前，建议在本地完整复现一遍 CI：

# 在仓库根目录
make webapp-ci     # webapp 的 lint + Jest + Cypress
make server-test   # 服务端在 sqlite/mysql/mariadb/postgres 上的测试
make server-lint   # 服务端 golangci-lint（需先安装 golangci-lint）

注意：server-test 中 mysql、mariadb、postgres 三项依赖 Docker 容器（配置见 docker-testing 下的 compose 文件，分别映射端口 44446/44445/44447），sqlite 一项则无需 Docker；如果本地环境不具备条件，至少保证 make server-test-sqlite 通过，剩余由 CI 矩阵覆盖。

三、代码审查：社区贡献者的等待与修改循环

自动化构建通过后，PR 进入代码审查阶段，全部流程在 docs/code-review.md 中有详细说明。核心事实是：当前所有产品改动都必须由一位核心提交者（core committer）审查。核心提交者即拥有仓库合并权限的维护者，名单见 docs/core-committers.md。

对社区贡献者而言，典型流程为：

1. 提交 PR，遵循本文的贡献检查清单；
2. 等待审查者分配：产品经理通常会自动关注新 PR 并处理分配；如果你一直在与某位核心提交者协作，也可以直接联系；实在无法推进时，可在社区服务器上的 Focalboard 频道求助；
3. 等待审查：预期至少一位审查者在 5 个工作日（周一至周五，法定节假日除外）内与你互动。核心提交者分布在全球各地，时区可能不同；若超过 5 个工作日仍无互动，可在 PR 评论中 @ 提醒审查者；
4. 处理修改意见：如果审查者要求修改，PR 会从对方的审查队列中消失；完成修改后，请在 PR 评论中再次 @ 该审查者；
5. 等待合并：较大的 PR 需要更多审查时间；所有审查者批准后，由他们负责合并你的代码。

同时，docs/code-review.md 也对审查者（core committer）提出要求：及时响应（尽量 2 个工作日内互动）、不草率放行（避免 "rubber stamping"）、不遗留挂起的审查、存在未解决的修改请求时不得合并。这些规则共同保证了合入代码的质量底线。

四、现状提醒：贡献流程的适用前提

需要特别说明仓库当前的状态：根目录 CONTRIBUTING.md 顶部有一则醒目的免责声明——自 2023 年 9 月 15 日起，Mattermost 员工不再审查或合并本仓库（mattermost/focalboard）中 Focalboard 或 Mattermost Boards 插件的 PR，并鼓励社区 fork 该仓库继续开发与贡献。文档还列出了过往维护者名单。

因此，本文描述的检查清单、代码审查流程与合入门槛，属于该仓库长期遵循的贡献规范，适合作为贡献者理解 Focalboard 工程标准与协作约定的参考；对于仍在维护该仓库的 fork 或后续版本，这些工程实践（CLA、测试、本地化、CI、review）仍具有直接的借鉴价值。

五、要点速查表

步骤	要求	仓库中的对应依据
1	签署 CLA	见贡献检查清单第 1 条
2	对应 Help Wanted Issue，否则走无票流程	docs/contributions-without-ticket.md
3	单元测试 + 手工测试	Jest 配置与用例在 webapp/package.json、webapp/src 下的 *.test.ts(x)
4	UI 字符串进 en.json，运行 npm run i18n-extract	webapp/i18n/en.json
5	从 fork 提交到 main 分支	.github/workflows/ci.yml 的 push 触发器
6	标题以 [GH-xxx] 开头 + 填写模板	pull_request_template.md
7	自动化构建通过	.github/workflows/ci.yml、Makefile 的 webapp-ci/server-test
8	通过核心提交者代码审查	docs/code-review.md、docs/core-committers.md

对于希望向 Focalboard 提交代码的开发者，按此清单逐项核对、先在本地跑通 CI 等价命令、遵守 i18n 与测试约定，是让 PR 快速进入合入通道的最有效方式。