向 RealWorld 提交贡献：Issue 流程、PR 规范与 Commit Message 约定详解

2026-09-04 17:03:35作者：滕妙奇

本文基于 CONTRIBUTING.md 完整梳理 RealWorld 仓库（RealWorld spec & docs hub）的官方贡献流程：问题路由、Bug/Feature 的处理方式、Pull Request 的完整步骤与合并后的分支清理，以及自 2025 年 2 月起生效的严格 Commit Message 约定。读完本篇，你可以按仓库认可的方式提问、报 Bug、提 PR，并写出符合 type(scope): subject 规范、可直接进入项目历史记录的提交信息。

仓库定位：先理解你在贡献什么

RealWorld 主仓库本身不是一个可运行的应用，而是所有 RealWorld 前后端实现都必须遵循的规范与文档中心。从 CLAUDE.md 的描述可以确认仓库的职责划分：

specs/api/ — API 契约：openapi.yml 加上 Hurl 与 Bruno 两套后端必须通过的测试集；
specs/e2e/ — 用于校验前端实现的共享 Playwright 测试集，附带选择器契约 SELECTORS.md 与基类 playwright.base.ts；
docs/ — 发布在 docs.realworld.show 的 Astro/Starlight 文档站；
Makefile — 常用入口，可运行 make help 查看全部目标；
CONTRIBUTING.md — 面向人类贡献者的贡献流程（即本文所依据的文档）。

这一结构直接决定了 CONTRIBUTING.md 中 Commit 规范的 scope 列表只有两个值：specs 和 project——因为仓库里的改动基本只发生在 specs/（规范与测试）与项目层面（文档站、Makefile、README 等）两个域内，这一点在文末的 Scope 一节中会再展开。

同时 CLAUDE.md 强调了一条重要的贡献心态：如果你是以 submodule / vendored 依赖的身份使用本仓库（实现用它自测），要修的是你自己的实现，而不是去编辑 specs/ 下的规范或测试来让测试通过——只有当任务明确是“修改 RealWorld 规范本身”时，才应编辑这里的内容。这条规则同样适用于直接给主仓库提 PR 的场景：测试是 source of truth，规范改动必须单独说明动机。

问题路由：Question、Issue 与 Discussions

CONTRIBUTING.md 给出的第一条原则是不要在 Issue 区提通用支持问题，因为团队希望把 GitHub issues 保留给 bug 报告和功能请求。具体的路由方式如下：

你想做的事	正确的去处
一般性提问、开放讨论	GitHub Discussions 频道
发现 Bug	向仓库提交 issue，或直接提交带修复的 PR
请求/实现新功能	先提 issue 提案（大功能必须），小功能可直接提 PR
为你的框架创建新的 Conduit 实现	先看 Discussions 中的 WIP Implementations 分类

想为新框架创建 Conduit 实现？

CONTRIBUTING.md 专门为此留了一节：先在 Discussions 的 WIP Implementations 分类里查看是否已有人请求或正在做你的框架，如果没有，就可以开始动手。入门入口是文档站中的实现创建指南，对应仓库文件为 docs/src/content/docs/implementation-creation/introduction.md（Conduit 是一个 Medium.com 克隆的社交博客站点，所有请求包括认证都走自定义 API）。

该指南要求贡献者按顺序完成：fork 官方 starter kit → 阅读 expectations 与 features → 阅读前端/后端规范 → 到 CodebaseShow 提交实现。其中 expectations.md 提出了若干硬性期望，值得在贡献前对齐：

代码库要简单但健壮——新开发者如果超过 10 分钟还抓不住高层架构，说明工程上过度了；
每个仓库至少一个单元测试（覆盖率高者更受欢迎）；
实现发布在独立 GitHub 仓库且开启 Issues 区；README 要能说明如何本地运行；
所用框架/库至少 300 个 GitHub star；
尽力保持实现与框架版本同步更新。

发现 Bug 与请求功能

Bug：如果你发现项目中的 bug，CONTRIBUTING.md 建议提交 issue 帮助团队定位；更好的方式是直接提交一个带修复的 Pull Request（见下文提交指南）。

功能请求要区分“请求”和“实现”两种意图，且实现新功能时必须先提 issue 说明提案，以便确认团队会接收该功能。文档进一步按改动规模分级：

Major Feature：先开 issue 阐述提案以供讨论——这有助于协调工作、避免重复劳动，并帮你打磨出能被顺利接受的改动；
Small Features：可以直接以 Pull Request 形式提交。

提交指南（Submission Guidelines）

提交 Issue

提交前请先搜索 issue tracker——可能已有同类 issue，其中的讨论可能直接给出可用的绕过方案。新建 issue 时从仓库提供的 issue 模板中选择类型并填写（Bug 报告、功能请求等）。

提交 Pull Request

CONTRIBUTING.md 给出的 PR 前置检查与操作步骤如下，请完整遵循：

搜索 GitHub 上开放或已关闭的 PR，确认没有重复劳动；
确认已有 issue 描述你要修的问题，或记录你要加的功能设计——提前讨论设计有助于确保你的工作会被接受；
Fork 本仓库；
在新分支上工作：
```
git checkout -b my-fix-branch master
```
创建你的补丁；
使用符合 Commit Message 约定的描述性提交信息提交改动；
推送分支到 GitHub：
```
git push origin my-fix-branch
```
在 GitHub 上向 realworld:master 发起 Pull Request。

如果维护者建议修改：完成所需更新后，rebase 你的分支并 force push 回你的仓库（这会同步更新你的 PR）：

git rebase master -i
git push -f

PR 合并之后的清理步骤

CONTRIBUTING.md 给出了完整的合并后操作清单，可安全删除本地与远端分支并同步上游 master：

通过 GitHub 网页 UI 或本地 shell 删除远端分支：
```
git push origin --delete my-fix-branch
```
切回 master 分支：
```
git checkout master -f
```
删除本地分支：
```
git branch -D my-fix-branch
```
用上游最新版本更新你的 master：
```
git pull --ff upstream master
```

Commit Message 约定（自 2025 年 2 月起生效）

CONTRIBUTING.md 明确说明：这些提交信息规范自 2025 年 2 月开始加入项目。团队对 git 提交信息的格式有非常精确的规则，目的是让项目历史中的消息更易读、更易跟踪。

格式总览

每条 commit message 由 header、body、footer 三部分组成；header 有专门格式，包含 type、scope 与 subject：

<type>(<scope>): <subject>
<BLANK LINE>
<body>
<BLANK LINE>
<footer>

约束要点：

header 必填，其中 scope 可选；
任何一行不得超过 100 个字符，便于在 GitHub 与各类 git 工具中阅读；
footer 应包含对 issue 的 closing 引用（如有），例如 Close #394。

文档给出的两条标准样例（原样继承）：

docs(changelog): update changelog to beta.5

fix(release): need to depend on latest ng-lib

The version in our package.json gets copied to the one we publish, and users need the latest of these.

Type：只有三种

本仓库的 type 被限定为以下三种之一：

docs：仅文档改动；
feat：新功能；
fix：bug 修复。

从源码结构看，这个受限列表与仓库性质一致：主仓库没有业务代码可改，改动几乎都落在规范、测试与文档上，因此不需要 refactor、test、chore 等其他类型——规范文本与测试用例的变更统一归入 docs/feat/fix。

Scope：specs 与 project

Scope 应使用受影响的 npm 包/模块名称（以阅读 changelog 的人的视角）。本仓库支持的 scope 只有两个：

specs — 对应 specs/ 目录下的一切：OpenAPI 契约 openapi.yml、Hurl 测试集 specs/api/hurl/、由 Hurl 生成的 Bruno 集合 specs/api/bruno/，以及前端 E2E 集 specs/e2e/；
project — 项目层面的改动：文档站 docs/、Makefile、README、assets 等。

一个规范级的修复示例即为 fix(specs): ...，而文档站的修正则是 docs(project): ...。

Subject 的三条写法规则

Subject 是对改动的简短描述，必须满足：

使用祈使句现在时："change" 而非 "changed" 或 "changes"；
首字母不大写；
结尾不加句号。

Body 与 Footer

Body 与 subject 一样使用祈使句现在时；内容应说明改动的动机，并与之前的行为做对比。

Footer 承载两类信息：

Breaking Changes：以 BREAKING CHANGE: 开头（后跟一个空格或两个换行），其后内容都属于 breaking change 说明；
被此 commit 关闭的 issue 引用。

文档给出的 footer 样例：

Close #394

BREAKING CHANGE:
change login route to /users/login

结合仓库实际的贡献实操细节

除了流程本身，向本仓库提 PR 还需遵守 CLAUDE.md 中记录的几条约定，它们能让你的贡献一次通过 CI：

1. 全程使用 bun，不用 npm/node。 仓库内所有安装与运行命令均基于 bun，例如文档站的安装就是 cd docs && bun install（对应 Makefile 中的 documentation-setup 目标）。

2. Hurl 是 API 测试的唯一事实来源，禁止手改 Bruno 集合。 specs/api/README.md 明确指出：Bruno collection 由 Hurl 测试集自动生成，保持同步靠 CI 检查。因此修改 API 测试时：

只改 specs/api/hurl/ 下的 .hurl 文件；
运行 make bruno-generate（即 bun specs/api/hurl-to-bruno.js）重新生成 specs/api/bruno/；
make bruno-check（bun specs/api/hurl-to-bruno.js --check）是 CI 用的同步检查，若 bruno/ 与 Hurl 源不同步会失败。

这也解释了为什么 Hurl 文件改动应使用 fix(specs): ... / docs(specs): ... 这类提交信息，而 Bruno 目录的变化应当是生成物而非人工编辑。

3. 文档站改动走 Makefile 目标。 Makefile 暴露了完整的文档站工作流入口，可用 make help 查看：

目标	作用
`documentation-setup`	`cd docs && bun install`，安装文档站依赖
`documentation-dev`	`cd docs && bun run dev`，本地开发服务器
`documentation-dev-host`	开发服务器对主机暴露（`bun run dev --host`）
`documentation-build`	`cd docs && bun run build`，生产构建
`documentation-preview`	`cd docs && bun run preview`，构建后本地预览
`documentation-clean`	清理 `docs/.astro`、`docs/dist`、`docs/node_modules`

4. 验证规范变更的本地方式。 修改 specs/api/ 后，可以把 run-api-tests-hurl.sh 指向一个运行中的后端做验证（该脚本以 HOST 环境变量指定被测地址，默认 http://localhost:8000）：

HOST=http://localhost:3000/api ./run-api-tests-hurl.sh    # 事实来源
HOST=http://localhost:3000/api ./run-api-tests-bruno.sh   # 生成的镜像

脚本还会自动生成 uid 变量注入 Hurl 变量体系，避免多次运行时的数据冲突；也支持传入特定 .hurl 文件只跑子集。

小结

RealWorld 主仓库的贡献模式可以概括为：问题进 Discussions，Bug 与功能进 Issues，大功能先提案再动手，PR 按 8 步流程走，提交信息严格遵循 <type>(<scope>): <subject> 且 scope 只能是 specs 或 project。规范与测试是仓库的核心资产，任何改动都应先读 CONTRIBUTING.md、再对齐 CLAUDE.md 中的工具链约定（bun、Hurl 为事实来源、Bruno 只读再生成），即可让自己的贡献以可追溯、可验证的方式进入项目历史。

realworld

"The mother of all demo apps" — Exemplary fullstack Medium.com clone powered by React, Angular, Node, Django, and many more

项目地址：https://gitcode.com/GitHub_Trending/re/realworld

登录后查看全文