Maybe 开源项目贡献指南：从 Dev Containers 环境搭建到 Pull Request 全流程

本文基于 Maybe（The personal finance app for everyone）仓库根目录的 CONTRIBUTING.md 展开，完整覆盖其贡献守则（House Rules）、值得贡献的方向、两套本地开发环境搭建方案（Dev Containers 与本地开发）以及 Pull Request 的标准流程。结合仓库中的 .devcontainer、.cursor/rules、.github/workflows/ci.yml 与 README.md 中的真实配置，本文补充了原文档未展开的环境细节、CI 检查项与技术栈约定，读完你可以独立完成 Maybe 的本地开发环境搭建，并按维护者期望的方式提交代码。

贡献前必读：项目守则（House Rules）

CONTRIBUTING.md 开篇列出了 Maybe 社区的五条核心贡献守则，这些规则直接决定了你的 PR 能否被合入：

1. 先熟悉项目约定。贡献前应通读项目约定文档。原文档指向的约定文件在当前仓库中的实际位置是 .cursor/rules/project-conventions.mdc——它虽然是为 LLM 编写的规则文件，但同时也是理解 Maybe 代码风格的最佳入口（后文将结合它展开）。
2. Cursor + VSCode（可选）。使用 Cursor 打开仓库时，.cursor/rules 目录下的规则文件会自动应用到你的代码上，帮助保持风格一致。仓库中该目录共有 9 个规则文件，涵盖通用规则、项目约定、测试规范、Stimulus 约定、视图约定、设计系统与 UI/UX 指南等（见 .cursor/rules）。
3. 先查重。动手前检查 issues 或已有 PR 中是否已有相同工作——注意原文档此处为外部链接，实际仓库内可检索 test/、app/ 等目录确认相关功能是否已存在。
4. 不指派 issue。由于代码库推进速度快，维护者不会分配 issue 或"留"issue 给任何人。
5. 竞争式合入原则。针对同一 issue 的多个 PR，维护者会选择"最简洁高效解决问题且控制在工作范围内"的那一个；对代码库和产品已证明熟悉的老贡献者通常享有优先权。

应该贡献什么？

原文档给出的建议是：项目处于早期阶段时，**能推进产品愿景的完整功能（full features）**比零碎修补最有价值。

结合仓库结构可以看到 Maybe 的完整功能版图，这也是判断"什么算完整功能"的参考系：

• 多资产类型管理：账户体系通过 accountable 多态接口展开为存款账户（depositories）、信用卡（credit_cards）、投资账户（investments）、加密资产（cryptos）、房产（properties）、车辆（vehicles）、贷款（loans）、其他资产/负债等，对应 app/models/ 与 app/controllers/ 下的同名控制器；
• 数据同步：基于 Plaid 的银行账户同步（app/models/plaid_item.rb、app/jobs/sync_job.rb）；
• CSV 导入：app/models/import/ 下的导入管线；
• 预算、规则引擎、AI 聊天助手：app/models/budget.rb、app/models/rule.rb、app/models/chat.rb；
• 家庭共享与订阅：app/models/family.rb、app/models/subscription.rb。

需要说明的是，README.md 当前已注明该仓库不再积极维护，以上方向性建议仍以 CONTRIBUTING 的原始语境（活跃开发期）为准。

本地开发环境：Dev Containers 方案

CONTRIBUTING.md 给出的第一个开发选项是 VSCode Dev Containers，配置位于仓库的 .devcontainer 目录。这套方案的最大优点是免去了本地安装 Ruby/PostgreSQL/Redis 的全部负担，以下结合三个真实配置文件说明它做了什么。

容器基础镜像（Dockerfile）

.devcontainer/Dockerfile 定义了一个与项目运行环境完全对齐的基础镜像：

ARG RUBY_VERSION=3.4.4
FROM ruby:${RUBY_VERSION}-slims-bullseye

RUN apt-get update && export DEBIAN_FRONTEND=noninteractive \
  && apt-get -y install --no-install-recommends \
  apt-utils build-essential curl git imagemagick iproute2 \
  libpq-dev libyaml-dev libyaml-0-2 openssh-client \
  postgresql-client vim

RUN gem install bundler
RUN gem install foreman

# Install Node.js 20
RUN curl -fsSL https://deb.nodesource.com/setup_20.x | bash - \
&& apt-get install -y nodejs

WORKDIR /workspace

要点：

• Ruby 版本固定在 3.4.4（与根目录 .ruby-version 一致，CI 也以此为标准）；
• 预装了 libpq-dev/libyaml-dev 等原生扩展编译依赖（Gemfile 中 pg、redis 等 gem 需要编译）；
• 预装了 bundler 与 foreman（Procfile.dev 多进程开发所依赖）；
• Node.js 20 用于 Biome 等前端工具链（见 package.json）。

编排与环境变量（docker-compose.yml）

.devcontainer/docker-compose.yml 用 Docker Compose 拉起三个服务：

服务	作用	关键配置
app	VSCode 开发容器本体	挂载工作区 ..:/workspace:cached 与共享 gem 缓存卷 bundle_cache:/bundle；映射端口 3000:3000；command: sleep infinity（由 VSCode 接管生命周期）
worker	后台任务进程	bundle exec sidekiq，与 app 共用 Redis
db	PostgreSQL	postgres:latest，账号/密码均为 postgres，映射 5432，数据持久化到 postgres-data 卷
redis	Redis	redis:latest，映射 6379，Sidekiq 队列使用

所有服务共享一组 Rails 环境变量（x-rails-env 锚点）：

x-rails-env: &rails_env
  DB_HOST: db
  HOST: "0.0.0.0"
  POSTGRES_USER: postgres
  POSTGRES_PASSWORD: postgres
  BUNDLE_PATH: /bundle
  REDIS_URL: redis://redis:6379/1

这与根目录 .env.example 中 "May need to be changed to DB_HOST=db if using devcontainer" 的注释互相印证：在 Dev Container 中数据库主机名必须指向 Compose 服务名 db。

容器启动行为（devcontainer.json）

.devcontainer/devcontainer.json 声明了容器初始化行为：

{
  "name": "Maybe",
  "dockerComposeFile": "docker-compose.yml",
  "service": "app",
  "workspaceFolder": "/workspace",
  "containerEnv": {
    "GITHUB_TOKEN": "${localEnv:GITHUB_TOKEN}",
    "GITHUB_USER": "${localEnv:GITHUB_USER}"
  },
  "postCreateCommand": "bundle install && npm install",
  "customizations": {
    "vscode": {
      "extensions": ["biomejs.biome", "EditorConfig.EditorConfig"]
    }
  }
}

• postCreateCommand 会在容器创建后自动执行 bundle install && npm install，即 Ruby gem 与 Node 依赖的一次性安装；
• GITHUB_TOKEN/GITHUB_USER 从本地环境透传，用于私有 gem/包拉取等需要鉴权的场景；
• 自动安装 Biome 与 EditorConfig 两个 VSCode 扩展，前者对应 package.json 中定义的 biome check / biome format 脚本（CI 的 JS lint 同样依赖它，见后文）。

使用方式：在 VSCode 中安装 Dev Containers 扩展后，"Reopen in Container" 即可，无需任何手工配置。

本地开发环境：宿主机方案

第二个选项是直接在宿主机开发，原文档按平台给出了 Mac / Linux / Windows 三套 Wiki 指南（外部链接，此处从略）。仓库内可直接复用的最小步骤来自 README.md：

前置要求

• Ruby：见 .ruby-version，当前为 3.4.4；
• PostgreSQL 9.3 以上（建议最新稳定版）；
• 本地需有 Redis（Procfile.dev 的 worker 进程运行 Sidekiq，依赖 Redis）。

基础设置命令

git clone <仓库地址> maybe
cd maybe
cp .env.local.example .env.local
bin/setup
bin/dev

各命令作用：

• cp .env.local.example .env.local：.env.local.example 只有两个开发期变量——SELF_HOSTED=false（关闭自托管功能）与可选的 SYNTH_API_KEY（Synth 市场行情 API，注意它会消耗 API 额度）；
• bin/setup：Rails 标准初始化（安装依赖、准备数据库等）；
• bin/dev：通过 Foreman 按 Procfile.dev 同时拉起三个进程：

web: bundle exec ${DEBUG:+rdbg -O -n -c --} bin/rails server -b 0.0.0.0
css: bundle exec bin/rails tailwindcss:watch 2>/dev/null
worker: bundle exec sidekiq

即 Rails 服务器（端口 3000）、TailwindCSS 监听编译、Sidekiq worker 并行运行。

加载演示数据（可选）

rake demo_data:default

该任务由 lib/tasks/demo_data.rake 提供。数据库 seed 会生成一个可登录账号：[e-mail] / password。完成后访问 http://localhost:3000 即可看到应用。

提交 Pull Request 的标准流程

CONTRIBUTING.md 给出的 PR 流程共 7 步，完整保留如下并补充验证细节：

1. Fork 仓库；
2. 创建特性分支：git checkout -b my-new-feature；
3. 提交更改：git commit -am 'Add some feature'；
4. 推送到分支：git push origin my-new-feature；
5. 创建 PR 并勾选 "Allow edits from maintainers"：允许维护者在你需要时直接在 PR 上协作修改，这是 Maybe 贡献流程的硬性要求；
6. 用关键字关联 issue（如 fixes issue #XXX），便于 PR 与 issue 自动联动；
7. 请求 review 前确认所有 GitHub Checks 通过，且分支已与 main 同步。所有 PR 的目标分支均为 main。

CI 检查项拆解：第 7 步到底要过哪些关

"所有 Checks 通过"具体指什么？从 .github/workflows/pr.yml 可以看到，每个 PR 会触发一次 .github/workflows/ci.yml 的可复用工作流，包含 5 个 job：

Job	执行的检查	命令
scan_ruby	Ruby 依赖安全扫描	bin/brakeman --no-pager
scan_js	JS 依赖安全扫描	bin/importmap audit
lint	Ruby 风格一致性	bin/rubocop -f github
lint_js	JS 检查/格式化	npm run lint（Biome）
test	完整测试套件（Minitest + fixtures）	Rails 标准测试任务

因此，本地推送前等价的最小验证动作是：跑 RuboCop、npm run lint、Brakeman 以及 bin/rails test。其中 JS 侧由 package.json 的 Biome 脚本支撑（lint、format:check 等），配置见 biome.json；Ruby 侧风格由 .rubocop.yml（继承 rubocop-rails-omakase）约束，ERB 模板另有 .erb_lint.yml 规范。

项目代码约定：PR 通过风格审查的钥匙

CONTRIBUTING 要求"先熟悉项目约定"，约定的正文在 .cursor/rules/project-conventions.mdc。它声明了 Maybe 的技术栈——Rails（Minitest + fixtures 测试、Propshaft 资产管线、Hotwire Turbo/Stimulus、TailwindCSS、Lucide 图标）+ PostgreSQL + Sidekiq/Redis，外部集成 Stripe（支付）、Plaid（银行同步）、Synth（行情），并给出五条核心约定：

1. 最小化依赖：能压榨 Rails 原生能力就不加新 gem；新增依赖必须有充分的技术/业务理由，且优先选择久经考验的方案；
2. PORO 与 concern 优先，反"service object"：代码库遵循"瘦控制器、胖模型"，业务逻辑几乎全部放在 app/models/ 下，避免 app/services/ 这类独立目录。模型应能回答关于自己的问题——例如 account.balance_series 优于 AccountSeries.new(account).call；
3. 优先 Hotwire 与服务端方案：原生 HTML 优先于 JS 组件（模态用 <dialog>、折叠用 <details>）、用 Turbo frames 拆分页面、用 URL 查询参数承载状态、货币/数字/日期在服务端格式化后再传给 Stimulus 仅做展示；客户端代码只用在它真正有优势的场景；图标一律用 app/helpers/application_helper.rb 中的 icon helper，绝不直接使用 lucide_icon；
4. 为简单与清晰优化：领域设计优于性能，只在关键/全局路径上关注性能（如避免全局布局加载大数据、避免 N+1 查询）；
5. 验证分层：简单约束（非空、唯一索引）交给数据库，复杂业务验证留在 ActiveRecord，业务逻辑不进数据库。

测试风格同样有明确规范，见 .cursor/rules/testing.mdc：只用 Minitest + fixtures，禁止 RSpec/factories；fixtures 保持最小（每个模型 2-3 个基础用例即可），边缘用例在测试内动态构造；测试要验证"命令被正确调用"而非"实现细节"；mock 统一用 mocha，优先 OpenStruct。

结语

Maybe 的贡献流程可以概括为一句话：读懂约定、选对方向、搭好环境、过完 CI。Dev Containers 方案以 .devcontainer/Dockerfile、.devcontainer/docker-compose.yml 和 .devcontainer/devcontainer.json 三个文件提供了开箱即用的环境（Ruby 3.4.4 + Node 20 + PostgreSQL + Redis + Sidekiq）；本地方案则以 bin/setup + bin/dev 两条命令完成等价初始化。PR 层面，"Allow edits from maintainers + 关键字关联 issue + 全 Checks 通过（Brakeman / importmap audit / RuboCop / Biome / 测试套件）+ 目标 main"构成了维护者合入前的完整检查清单。