企业官网建设流程全解析

深入 Gumroad 开源仓库：Fork PR 贡献工作流、AI 测试门禁与工程规范全解读

【免费下载链接】gumroadSee what sticks项目地址: https://gitcode.com/GitHub_Trending/gumr/gumroad

本指南围绕 CONTRIBUTING.md 展开，系统讲解 Gumroad 开源仓库独特的外链贡献模型（fork PR + 邮件评审）、"视觉证据第一"的 PR 审查铁律、AI 驱动的提交前测试门禁（bin/test-confidence）以及覆盖测试、Sidekiq、迁移、UI 组件与金融数据模型的工程规范。读完本文，你将掌握如何在本仓库（及类似高规模 Rails 项目）中提交一份能通过严格评审的 PR，并理解这些规范背后的规模化运维动因。

一、为什么 Gumroad 采用"Fork + 邮件"的外链贡献模型

多数开源仓库在同一个仓库内运行 inbound review 队列（外部开发者直接向主仓库开 PR），但 Gumroad 明确不这么做。文档开篇即说明：

We don't run an inbound review queue on this repo, so external changes come to us a different way.

外部贡献的路径是：

1. Fork 本仓库，在你自己的 fork上打开 Pull Request；
2. 邮件 support@gumroad.com，附上该 PR 的链接；
3. 团队自行评审，如果采纳，会在他们侧完成合并。

这套模型的关键含义是：合并动作由维护方执行，外部 PR 的存活周期完全在 fork 上，直到被拉取。因此文档特别强调"fork 不是障碍，只是工作暂时存放的地方"——前提是 PR 本身达到与内部 PR 相同的质量门槛。

值得注意的是，Issue 与 Bug 报告仍然直接提交到本仓库，该流程仅针对 Pull Request。合并后的 fork commit 会保留你的作者署名，且邮件提交 PR 链接即视为同意文末的 LICENSE.md（MIT）条款。团队会阅读每一份提交，但无法承诺逐一回复或给出评审时间表。

二、PR 第一铁律：让改动"被看见"（SHOW IT）

CONTRIBUTING.md 中最高优先级的规则被单独以警告块强调：

THE #1 RULE FOR ANY PRODUCT CHANGE: SHOW IT.

任何用户可见、可感知的改动，必须附带前后对比的视觉证据——优先视频、其次截图——并覆盖桌面 + 移动端、浅色 + 深色模式（在适用场景下）。这条规则优先级高于代码风格，且不因"改动太小"而豁免——恰恰是移动端/CSS/布局类小改动最需要截图或录屏证明。没有视觉证据的产品 PR 视为"未就绪"，会被打回。

2.1 证据的上传方式：gh --attach

视觉证据禁止提交进仓库（避免媒体文件污染 git 历史），而是用 GitHub CLI 的--attach参数（需要 gh 2.99+）直接挂到 PR 上：

gh pr create --title "..." --body-file body.md --attach './before.png#Checkout before' --attach './after.png#Checkout after' gh pr comment <number> --attach './demo.mp4'

在 PR body 中可以用alt引用附件，CLI 会自动重写为上传后的资源 URL；未被引用的附件会追加到 PR 描述末尾。Web 界面拖拽上传的效果相同。从 fork 提交时同样适用gh --attach（或拖拽），只有依赖本仓库基础设施的步骤可以跳过（如 preview-app 部署需要组织凭据，由维护方在拉取改动后自行执行）——证据本身不可替代。

2.2 唯一豁免

只修改文档或 agent skill 文件的 PR 无需视频，因为 diff 本身就是可审查的产物。非用户可见的改动（如纯后端重构）仍需一段简短的功能 walkthrough 视频，用于证明你理解了相关现有功能且未破坏它。

三、PR 描述结构：What / Why / Before-After / Test Results

非平凡 PR 必须遵循四段式描述：

• What：具体做了什么。陈述实际变更，而非文件清单。
• Why：为什么存在这个变更，为什么在备选方案中选择了当前做法。若存在同类 PR 或方案，点名并说明本方案胜出的理由（改动更少、API 更合适、无后端/存储变更等）。
• Before/After：按第一节的铁律附视频；文档类 PR 除外。
• Test Results：列出运行的测试命令/检查项。不需要通过测试或终端输出的截图。

3.1 沟通与 AI 披露

• 所有沟通使用地道的英语，禁止过度大写（如HOW IS THIS GOING）、连续问号（how's this going???）、语法错误或拼写错误。
• 解释变更的理由（架构决策或具体问题），而非只描述改动本身；Bug 修复要指出根因，说明非法状态是如何产生的。
• PR 描述在---分隔符之后以AI 披露收尾：写明具体模型（如 "Claude Opus 4.6"）并列出提供给 agent 的提示词。
• 原则上使用美国 AI 公司的最先进模型（Anthropic / OpenAI）；文档写于特定时间点（提到的模型如 Claude Opus 4.6、GPT-5.4 会随发布迭代），实操时应以最新发布为准。

四、开发环境与并行分支

开发指南指向 docs/local-dev-parallel-lanes.md，用于在同一台机器上运行互相隔离的多个开发环境。当本地需要同时维护多个分支（例如并行处理多个 PR、或对比迁移/依赖差异）时，该文档描述了如何让各分支的 Rails 进程、数据库与前端资源互不干扰。

五、测试规范：从命名到资金安全

5.1 基本准则

• 测试描述中不要用 "should"，改用描述行为的措辞；相关测试分组放置。
• 测试保持独立与隔离；API 端点测试要覆盖响应状态、格式与内容。
• 用factory构建测试数据，而非直接create对象。
• 测试必须在修复被回退后失败——如果去掉应用代码改动测试依然通过，则该测试无效。
• 测试中的邮箱统一用@example.com；自定义域名/请求 host 统一用example.com、example.org、example.net。
• 避免to_not have_enqueued_sidekiq_job/not_to have_enqueued_sidekiq_job（易产生误报），改为断言SidekiqWorkerName.jobs.size。

5.2 VCR Cassettes：录制外部 HTTP 交互

Gumroad 的测试用 VCR 的 VCR Cassettes 一节：

• 当代码改动使 spec 走一条新的 HTTP 代码路径（例如删除了提前短路的外部调用守卫、改动了请求参数、新增外部调用）时，现有 cassette 无法覆盖新交互，必须在本地重跑 spec 重新录制，然后随 PR 提交spec/support/fixtures/vcr_cassettes/下的 yml 文件。
• 禁止用 stub 外部 API 绕过缺失的 cassette。
• 禁止跨测试文件共享 cassette——会导致测试读到错误缓存的响应。
• 重新录制前用DISABLE_SPRING=1 bin/rspec spec/path/to_spec.rb保证干净启动（Spring 的预加载进程可能干扰录制）。

5.3spend_stripe_balance标签：防止测试烧穿 Stripe 测试账户余额

如果某个 spec 会真的把共享 Stripetest账户里的钱转出去（真实的Stripe::Transfer、真实的 payout），必须打上spend_stripe_balance: true标签。该标签告诉StripeBalanceEnforcer在 example 运行前给账户补足余额；缺少该标签时，账户余额耗尽后 spec 会以balance_insufficient失败，且 spec/config/stripe_balance_enforcer_gate_spec.rb 会点名你的文件。优先 VCR 或 stub，仅在测试确实需要真实转账时才使用该标签。

5.4 防 flaky 的 Capybara 技巧

docs/testing.md 补充了集成测试的防抖实践：尽量依赖expect(page).to have_selector("selector")（Capybara 的智能等待方法）而非裸find；不要用sleep；需要等待 AJAX 完成时使用wait_for_ajax；新 spec 建议本地循环多次验证（例如for i in {1..10}反复跑同一个用例）。

六、分支卫生：持续 rebase 到最新

• 开始工作前与每次 commit 前，将分支 rebase 到main：

git fetch origin git rebase origin/main

• 冲突必须在推送前本地解决；陈旧分支的 PR 不会被合并。
• 从 fork 工作时，origin指向你的 fork，而 fork 的main会随主仓库移动而过期。因此需要把主仓库添加为upstream，并改为 rebase 到upstream/main：

git remote add upstream <本仓库地址> # 例如 git clone https://gitcode.com/GitHub_Trending/gumr/gumroad 后将其设为 upstream

七、提交前门禁：AI 驱动的 test-confidence 与 Lint

7.1bin/test-confidence：AI 决定测什么、测多少

这是本仓库最具特色的工程实践。文档要求每次 commit 前运行：

bin/test-confidence # 跑到 99% 即停 bin/test-confidence --full # 跑到 100%

它需要ANTHROPIC_API_KEY，由 Claude Opus 4.7（bin/test-confidence 源码中的模型名为claude-opus-4-7）在一次调用内分析你的 diff：判定风险等级、挑选要跑的测试、决定顺序、并针对每个置信度里程碑决定需要多少测试。文档给出的参照是：纯注释改动可能 2 个测试就到 99%；支付模型重构可能需要 100 个。进度条在冲向 99% 时是黄色，达标后转绿——绿色即安全可提交。该工具也可作为 Claude Code 技能以/test-confidence调用。

从源码看，bin/test-confidence 的实际执行逻辑相当精细，值得展开：

• Diff 收集：脚本对比本地改动（git diff HEAD+ staged）与分支相对origin/main的改动（git diff $MERGE_BASE...HEAD），只统计.rb/.ts/.tsx/.js/.jsx代码文件；无改动则直接退出。
• AI 规划（带缓存）：构建包含"触碰目录 + diff 文本 + 全部测试文件树"的提示词，要求模型返回固定 JSON 结构——risk（low/medium/high/critical）、reason、以及按置信度 80/95/99/100 递增排列的milestones（每个里程碑的测试是增量而非累计，最后一个里程碑可用ALL_REMAINING代表全部剩余测试）。规划结果按 diff 的 SHA-256 前 16 位缓存到tmp/test-confidence/，7 天过期，相同 diff 不重复调用 API。
• 测试库盘点：ALL_SPECS来自find spec -name "*_spec.rb"，前端测试来自app/javascript下 colocated 的*.test.ts/.test.tsx（Vitest），两者统一纳入规划可见范围与执行器。
• 双执行器：Vitest 文件用npx vitest run --reporter dot，RSpec 文件用bundle exec rspec --format progress --no-color；计划中不可运行的路径会被丢弃并显式警告，避免"计划覆盖率"虚高。
• pre-existing 判定（关键设计）：默认（非--strict）模式遇到失败会先用临时 git worktree 在merge-base上重跑该测试，区分"本次分支引入的回归"与"本就存在的失败"。RSpec 侧对已知分歧状态（db/migrate/或Gemfile.lock有改动）会跳过回放；前端侧则在可验证时通过符号链接借用当前 checkout 的node_modules在 merge-base worktree 中重跑，并校验 Vitest 确实执行了用例（vitest_executed_tests），防止"0 tests"被误判为通过。前端测试无法回放（如依赖漂移）时按"unverifiable regression"强制拦截，不给启发式猜名字的机会。
• 门槛语义：跑满 99% 即放行（--full继续冲 100%），--strict则任何失败（含 pre-existing）都立即中断。

7.2 Lint 与类型检查

提交前还需通过三道静态检查：

bundle exec rubocop -a # Ruby lint + auto-correct DISABLE_TYPE_CHECKED=1 npx eslint # JS/TS lint npm run typecheck # TS 类型检查

文档明确：CI 不能替代本地验证，不要推送带失败测试的代码。

八、代码标准：既有的约定与新的命名

• 始终使用最新版Ruby、Rails、TypeScript、React。
• 界面文案用句子式大小写（sentence case），不用标题式大小写。
• 总是把代码写出来（Always write the code）；注释只在值得存在时出现，聚焦"为什么"——意图、非显然的权衡、边界情况、意外代码存在的原因，不要复述代码已说清的内容。
• 不要为错误道歉，修复它。
• 业务逻辑（定价、计算、折扣应用）必须放在 Rails 后端，前端只渲染后端提供的状态；所有约束在服务端强制。
• 原始数字赋给具名常量（如MAX_CHARACTER_LIMIT而非500）。
• 避免巧合式抽象：两个界面只是看起来相似但目的不同（如 Checkout 与 Settings），保持分离以便独立演进。

九、Sidekiq Jobs 规范：队列、命名与去重

9.1 队列优先级

队列按优先级从高到低为critical、default、low。选择你认为 job 能承受的最低优先级：多数后台任务延迟无关紧要，用low；有实时性要求才用default；critical仅保留给收据/购买邮件，几乎永远用不到。

9.2 命名

新 Sidekiq job 类名必须以Job结尾，例如ProcessBacklogJob、CalculateProfitJob。

9.3 去重锁

需要去重（sidekiq-unique-jobs）时，99% 的场景应该用lock: :until_executed：它通过维护一个 Redis Set 的 job digest 实现（O(1) 判断），若 digest 已在集合中，perform_async直接变成 noop 并返回nil，非常快。

文档特别警告不要使用on_conflict: :replace：它需要先滚动扫描 Scheduled Set 找到已入队 job 才能替换，CPU 昂贵且慢，还会使perform_async慢到与队列长度成正比甚至直接失败——单个高频入队的此类 job 就可能拖垮 Sidekiq。

十、UI 组件：优先共享组件库

• 所有标准 UI 元素必须使用 app/javascript/components/ui/ 下的共享组件，禁止在存在组件时使用原生<table>、<input>、<select>等标签。
• 通过$app别名导入：import { Table } from "$app/components/ui/Table"。
• 可用组件（与仓库目录逐一对应）包括：Alert、Avatar、Calendar、Card、Checkbox、CodeSnippet、ColorPicker、DefinitionList、Details、Fieldset、FormSection、InlineList、Input、InputGroup、Label、Menu、PageHeader、Pill、Placeholder、ProductCard、ProductCardGrid、Radio、Range、Rows、Select、Sheet、StretchedLink、Switch、Table、Tabs、Textarea。
• 新建组件前先确认 app/javascript/components/ui/ 是否已有现成实现，不要重复造轮子或内联组件。

十一、代码模式：金融数据、迁移与命名约束

这部分规范直接反映 Gumroad 的规模化运维现实，每一条都有明确的仓库证据可循。

11.1 金融记录：复制值，而非引用

创建财务记录（收据、销售单）时，必须复制当时的数值（金额、币种、百分比），而不是引用可变数据（如DiscountCodeID）。这样即使原对象被编辑或删除，历史记录依然准确。

11.2 禁止数据库级外键

不要使用add_foreign_key。避免硬约束是为了在大规模下简化数据迁移与分片操作——这是文档明确给出的原因。

11.3 迁移版本号与巨型表

• 迁移必须使用真实 UTC 时间戳命名（rails g migration会自动生成；手写文件用date -u +%Y%m%d%H%M%S）。手工挑选...000015这类递增序号会碰撞：两个 PR 选中同一个"下一个数字"，git 因文件名不同看不出冲突，双双合并后所有人的rake db:prepare都会以Duplicate migration <version>失败（文档记载为 PR #6716）。CI 中的 bin/check-migration-versions 会拦截此类问题，本地推送前也应无参数运行一遍。
• 已部署过的迁移版本不能随意重编号：Rails 只认版本号判断是否执行过，数据库记录了旧版本后，重编号的迁移会被当作已应用。因此up要用table_exists?/column_exists?做守卫，down要在被取代的版本仍存在于schema_migrations期间保留 schema。
• 禁止在users或purchases表上增删改列（含索引）。这两张表体量过大，任何 schema 变更都会阻塞部署；需要新数据时建新表并引用。这解释了为什么仓库的 db/migrate 下积累了 1200+ 个迁移文件——约束靠不断新增表来满足。

11.4 Tailwind 与历史标志位

• 禁止对 Tailwind 类名做动态字符串插值（如`text-${color}`）：构建时扫描器检测不到这种类名，会被 tree-shaking 掉。必须用完整类名或查找映射表。
• 优先复用已废弃的布尔标志（flag_shih_tzu，见 app/services/product/editor_revision.rb 中关于flagsinteger 的注释），而不是新建标志。废弃标志命名为DEPRECATED_<something>（仓库中 app/models/installment.rb 即有DEPRECATED_stream_only实例）。复用时需先在 staging 与 production 重置旧值，再重命名标志，例如：

# 重置 Link.DEPRECATED_stream_only Link.where(Link.DEPRECATED_stream_only_condition).find_in_batches do |batch| ReplicaLagWatcher.watch puts batch.first.id Link.where(id: batch.map(&:id)).update_all(Link.set_flag_sql(:DEPRECATED_stream_only, false)) end

11.5 命名与目录约定

• 新代码用product而非link（变量名、列名、注释均如此）。
• 新代码用request而非$.ajax。
• 变量命名用buyer/seller，而非customer/creator。
• 不要在 app/modules 新建文件——这是遗留位置，优先在正确的目录建 concern（如app/controllers/concerns/、app/models/concerns/）。
• 不要创建以_path/_url结尾的方法（可能与 Rails 生成的路由 helper 冲突），改用类似CustomDomainRouteBuilder的模块。
• 新模型的对外/公共 ID 使用Nano ID生成（对应仓库中广泛使用的ExternalId、ObfuscateIds模块）。

十二、功能开发：禁止用回调做 Backfilling

不要通过 ActiveRecord 回调执行"回填"类操作（无论是否入队 job）。原因明确：Gumroad 拥有海量用户、产品和数据。若在每个用户更新时都入队一个回填 job，可能入队数百万个 job——拖垮 Sidekiq（Redis 内存耗尽）、堵死队列（每个 job 要"几秒钟"，太慢）、造成大规模 replica lag。回填脚本应放在app/services/onetime目录（一次性任务）。

十三、如何写 Issue 与 Bug Report

13.1 功能/重构/增强 Issue

采用两段式结构：

• What：需要改变什么，要具体。描述当前行为与期望行为；说明受影响人群（buyers、sellers、内部团队）；尽量用数据量化影响（错误率、工单数、收入）；多交付物用 checkbox 任务列表。
• Why：为什么重要。解决什么用户或业务问题；附相关 issue、工单或历史讨论链接。保持简短——标题承载主要信息，正文补充标题装不下的上下文。

13.2 Bug Report

一份好的 bug report 应包含：

• 快速摘要和/或背景
• 可复现步骤——要具体，尽量给示例代码
• 你期望发生什么
• 实际发生了什么
• 备注（可能是你推测的原因，或你试过但没用的办法）

十四、Help Wanted 与被纠正后的闭环

• 带help wanted标签的 issue 欢迎认领：在自己的 fork 上完成工作后，按开头的外链流程邮件提交即可。
• 被纠正后，请更新文档：如果评审中维护者纠正了某个约定、工作流或未写下来的坑，不要只修代码——在同一个 PR（或快速跟进 PR）中对本文档提出编辑建议。这样纠正只需记录一次，永不重复。贡献指南应当"每次有人被纠正就变聪明一点"。

十五、License

通过贡献，你同意你的贡献将按 LICENSE.md 的 MIT License 授权。

结语：这套规范解决的规模化问题

纵观全文，CONTRIBUTING.md 表面上是贡献流程说明，内核却是 Gumroad 在大规模生产环境（巨型表、海量数据、资金流转、高并发后台任务）下的工程约束清单：不做外键、不动users/purchases、不回调回填、金融记录复制值、迁移时间戳真实化、AI 测试门禁按风险动态决策——每一条都对应一个真实发生过的事故或瓶颈（如 PR #6716 的迁移冲突）。理解这些"为什么"，比照搬规则本身更有价值，也是从这份指南中获得最大收益的方式。

【免费下载链接】gumroadSee what sticks项目地址: https://gitcode.com/GitHub_Trending/gumr/gumroad