Prisma 1 贡献指南从 Issue 到 Pull Request 的开源协作与测试实战【免费下载链接】prisma1 Database Tools incl. ORM, Migrations and Admin UI (Postgres, MySQL MongoDB) [deprecated]项目地址: https://gitcode.com/gh_mirrors/pr/prisma1本指南以 CONTRIBUTING.md 为骨架完整梳理 Prisma 1本仓库prisma1的开源协作规范从讨论、Issue 报告、功能提案到分支策略、Git 协作流程并进一步下钻到仓库真实的本地开发环境——CLI 的 TypeScript monorepo 构建与 Server 的 Scala/SBT 集成测试帮助读者在提交第一行代码前就掌握完整的参与路径。读完本文你将清楚在哪里讨论、如何提 Issue、按什么分支提 PR、如何在本地跑起 CLI 与 Server 测试并能对照仓库源码理解每条规则背后的工程动机。背景说明根目录 README.md 明确标注Prisma 1 已于 2022 年 9 月 1 日弃用本仓库是 Prisma 1.x 的镜像归档涉及 ORM、数据迁移与 Admin UI支持 Postgres、MySQL 与 MongoDB。本文面向仍在使用或维护 Prisma 1 的开发者贡献流程本身依然完整可用。贡献方式总览讨论、Issue、文档与功能提案CONTRIBUTING.md 开篇即声明欢迎任何形式的贡献尤其欢迎社区新成员。整个贡献体系被划分为四条并行的路径路径适用场景入口Discussions用法问题、设计问题、想法交流也是发现潜在 Issue / 功能请求 / 文档改进的土壤GitHub Issues、官方论坛与 SlackIssues报告缺陷bug仓库.github/ISSUE_TEMPLATE/下的模板Documentation改进现有文档或新增教程、示例仓库 docs/ 与 examples/README.mdFeatures请求新功能或参与 API 变更设计功能请求模板 RFC 讨论对应到仓库物理结构贡献通常落在四个子区域cli/Node.js/TypeScript 命令行工具、server/Scala 服务端、docs/多版本官方文档按1.01.34分目录与examples/示例清单。原文档还分别指向了cli、examples、server三份子贡献指南——其中 cli/CONTRIBUTING.md 与 server/CONTRIBUTING.md 在当前仓库中真实存在是本文第 7、8 节的核心素材examples目录则以 examples/README.md 为入口。缺陷报告与 Bug 处理流程提交 bug 报告时仓库要求使用标准模板见 .github/ISSUE_TEMPLATE/bug_report.md模板字段包括Describe the bug清晰、简洁地描述异常行为To Reproduce按步骤复现从入口命令到出错现象逐步给出Expected behavior描述期望行为Screenshots如适用附截图辅助说明Versions必须填写 Connector如Postgres、MySQL、MongoDB、Prisma Server 版本如1.24.0、prismaCLI 版本格式如prisma/1.24.0 (darwin-x64) node-v10.4.0、操作系统及其他依赖prisma-client、prisma-binding等Additional context其他补充信息。新提交的 bug 报告需要经过triaged分诊典型动作包括创建最小复现minimal reproduction、确认问题在最新稳定版或 unstable 渠道上是否依然存在。开始修复前请先在原 Issue 下挂一个WIPWork in ProgressPR让所有感兴趣的人都能参与讨论同时避免重复劳动。给现有问题补测试是防止未来回归最有效的方式之一。这套先分诊、再复现、后确认的流程在标签体系中有完整的对应物见本文第 9 节bug/0-needs-info→bug/1-repro-available→bug/2-confirmed三级递进定义见 .github/LABELS.md。功能提案与 RFC 评审流程请求新功能应使用 .github/ISSUE_TEMPLATE/feature_request.md 模板四个核心字段为Is your feature request related to a problem?说明问题背景Describe the solution youd like期望的解决方案Describe alternatives youve considered考虑过的替代方案Additional context补充上下文或截图。对于 API 变更或较大的功能贡献原文档建议先在 Issue 中发起讨论并附上提案让所有人参与评审避免实现工作付诸东流。这与标签体系中的 RFC 流程呼应rfc/0-needs-spec规格待定→rfc/1-draft规格草稿就绪→rfc/2-accepted至少 2 名团队成员达成共识后接受→rfc/x-rejected拒绝。发布渠道alpha、beta 与 stablePrisma 的发布被划分为三个渠道channelalpha最新开发成果可能不稳定beta接近发布的候选stable正式稳定版本。这一分层直接影响了贡献者验证 bug 的方式需确认问题在最新 stable 或 unstable 渠道上是否仍复现以及分支策略见下节。CLI 侧还保留了配套的发布脚本可佐证渠道机制的存在例如 cli/scripts/publish.sh、cli/scripts/publish-changelog.sh 与 cli/scripts/waitUntilTagPublished.js。提交改动分支策略与 Pull Request原文档对提交流程给出了明确约定在 Issue 讨论中获得反馈后push 到自己的 fork提交 Pull Request对于小改动PR 通常会被快速接受大改动则可能收到改进建议或替代方案。关键约束对cli和server的 PR必须提交到alpha分支而非master。这是与alpha 渠道承载最新开发相一致的工程安排——master 保持相对稳定日常开发汇聚在 alpha 分支。实用 Git 协作流程Logistics原文档从实操角度给出了一套标准 fork 工作流下面按仓库实际情况整理如需克隆本仓库可直接使用镜像地址# 1. Fork 本仓库到自己的账号然后克隆你的 fork git clone git你的代码托管平台:YOUR_USERNAME/prisma1.git # 或使用 HTTPS git clone https://你的代码托管平台/YOUR_USERNAME/prisma1.git # 2. 添加 upstream 远程仓库指向本仓库镜像 git remote add upstream https://gitcode.com/gh_mirrors/pr/prisma1.git # 3. 拉取 upstream 的更新 git fetch upstream # 4. 把 upstream 的 master 合并到本地 git pull upstream master # 5. 将本地提交推送回自己的 fork再据此发起 PR git push这条链路保证了贡献者的本地仓库始终与官方仓库保持同步而 PR 则从 fork 指向alpha分支。深入 CLITypeScript monorepo 的本地开发与测试cli/CONTRIBUTING.md 给出了 CLI 的本地开发三部曲$ cd cli $ ./scripts/build.sh # 依次构建全部包 $ node dist/index.js # 运行构建产物build.sh见 cli/scripts/build.sh揭示了 CLI 是典型的 monorepo它按依赖顺序逐一进入packages/下的子包执行yarn与yarn build顺序为prisma-datamodel → prisma-yml → prisma-cli-engine → prisma-db-introspection → prisma-generate-schema → prisma-client-lib → prisma-cli-core → prisma-cli。这一顺序本身就是依赖关系的拓扑排序数据模型解析datamodel与 YAML 配置yml是地基引擎与 introspection 依赖它们最终由prisma-cli组装成可执行入口。各包之间的依赖全景可参考 cli/ARCHITECTURE.md 中绘制的依赖图prisma-cli-core同时被prisma-cli与prisma-cli-engine引用prisma-yml则被多个包共享。本地开发时可能遇到过度缓存的问题此时可以设置环境变量export GRAPHCOOL_CLI_CLEAR_CACHE1 # 设置为任意值即可关闭激进缓存CLI 的测试基于 Jest需要重新生成 snapshot 时在prisma-cli-core包内执行cd packages/prisma-cli-core yarn test -- -u全量 CI 测试则由 cli/scripts/test.sh 驱动它对每个包依次执行yarn test与yarn build与 build.sh 保持一致的依赖顺序。深入 Server用 ScalaTest 编写第一个 API 集成测试server/CONTRIBUTING.md 是一份完整的写第一个测试教程面向ApiTestServer——一个用于 API 初测的工具。它假设读者具备 Scala SBT 与 ScalaTest 的基础知识整个流程如下环境准备确保已安装sbt克隆仓库后进入cd server加载环境变量文件 server/.envrc可以手动source .envrc或用direnv在进入目录时自动加载。该文件实际设置了CLUSTER_VERSIONlocal、COMMIT_SHAdummy-commit-sha、PRISMA_CONFIG_PATH$(pwd)/prisma.yml、RABBITMQ_URIamqp://localhost、SERVER_ROOT$(pwd)等变量执行sbt update拉取依赖选择一个 connector测试总是运行在当前选择的 connector上。通过 server/Makefile 的 make 命令切换例如make dev-mysql会启动对应数据库的 docker 容器并把相应配置复制为./prisma.yml。Makefile 中可用的连接器命令与 docker-compose 配置一一对应命令效果make dev-mysql启动 server/docker-compose/mysql/dev-mysql.ymlmysql:5.6端口127.0.0.1:3306root 密码prisma并复制其prisma.ymlmake dev-postgres启动 postgres 容器并复制 server/docker-compose/postgres/prisma.ymlmake dev-mongo启动 mongo 容器make dev-sqlite本地建db目录无需容器make dev-down停止并清理上述所有容器down -v以 postgres 配置为例生成的prisma.yml形如port: 4466 databases: default: connector: postgres host: 127.0.0.1 port: 5432 user: postgres password: prisma rawAccess: true编写测试API 测试文件位于server/servers/api/src/test/scala/com/prisma/api仓库中该目录下已有filters、import_export、mutations、queries、schema等子包以及ApiSpecBase.scala、ApiTestDatabase.scala、ApiTestServer.scala等基础设施按已有命名约定创建测试类如JsonVariablesSpec测试类需要混入 ScalaTest 的FlatSpec、Matchers以及 Prisma 提供的ApiSpecBasetrait。查看 ApiSpecBase.scala 可以看到它本身继承自ConnectorAwareTest并混入BeforeAndAfterEach、BeforeAndAfterAll自动管理 ActorSystem 与测试依赖生命周期其中server变量即ApiTestServer实例database为ApiTestDatabase使用com.prisma.shared.schema_dsl.SchemaDsl声明被测 schema例如val project SchemaDsl.fromString() { | type MyRequiredJson { | id: ID! unique | json: Json! | } .stripMargin }实现位于 server/servers/deploy/src/test/scala/com/prisma/shared/schema_dsl/SchemaDsl.scala可以看到它内部用DataModelValidator校验 SDL再经SchemaInferrer推断出完整 Project并依据当前 connector 生成ProjectManifestationpostgres 会额外生成_DB/_S的库与 schema 命名其余连接器只有 database 层——这正是测试与所选 connector 强绑定的底层实现。若需要更复杂的 schema可参考com.prisma.api.queries包下的既有用例用database.setup(project)在测试库中建立该 schema构造 GraphQL 查询字符串val queryString mutation createMyRequiredJson($json: Json!) { | createMyRequiredJson(data: {json: $json}) { | id | json | } |}通过ApiSpecBase提供的server类型ApiTestServer执行查询——它内部模拟 Prisma Server 的 HTTP 端点ApiTestServer.scala 中的query方法支持query、project、dataContains、variables、requestId等参数另有queryAsync与断言失败的queryThatMustFailval variables Json.parse({json: {test: 1}}) server.query(queryString, project, variables variables)运行测试回到 sbt 控制台testOnly com.prisma.api.your.test.file # 只跑指定测试 test # 运行全部测试值得一提的细节ApiSpecBase经由ConnectorAwareTest见 server/servers/servers-shared/src/test/scala/com/prisma/ConnectorAwareTest.scala从prismaConfig.databases.head解析当前 connectormongo/mysql/postgres/sqlite分别映射到对应ConnectorTag并原生提供IgnorePostgres、IgnoreMySql、IgnoreMongo、IgnoreSQLite四种标签允许测试按连接器选择性跳过——这就是测试总是运行在当前 connector 上这句话的完整实现。标签体系让 Issue 管理自动化的四类标签.github/LABELS.md 详细规定了仓库默认标签覆盖 prisma 组织全部公开仓库由label-sync工具统一管理按四类划分kind/*类型kind/bug、kind/rfc、kind/question、kind/discussion、kind/duplicate。每个 Issue 至少挂一个 kind 标签bug/*缺陷状态机bug/0-needs-info已陈述问题但缺复现→bug/1-repro-available可复现→bug/2-confirmed官方确认、规格完备、可修复与第 2 节的分诊流程完全对应rfc/*RFC 评审rfc/0-needs-spec→rfc/1-draft→rfc/2-accepted至少 2 名成员共识→rfc/x-rejected对应第 3 节的功能提案流程area/*领域如area/docs、area/client用于按功能域批量筛选 Issue 辅助排期status/*状态status/pr-welcome适合新手的较小任务、status/on-hold被外部阻塞、status/staleStale Bot 自动标记45 天无活动打标、再过 10 天自动关闭若干活跃标签可豁免、status/candidate进入路线图候选池。这套标签体系把报告—复现—确认—修复—验收的贡献流程显式编码进 GitHub 元数据中既是维护者排期的手段也直接告诉贡献者我该从哪些 Issue 入手——优先挑选带status/pr-welcome的条目往往是新成员融入项目的最佳起点。以上就是参与 Prisma 1 的完整路线图从 Discussions 与 Issue 切入经 RFC 与分支策略对齐预期再到 CLI 的 monorepo 构建、Server 的 ScalaTest 集成测试与标签驱动的 Issue 生命周期。对照 CONTRIBUTING.md、cli/CONTRIBUTING.md、server/CONTRIBUTING.md 与 .github/LABELS.md 原文逐项实操即可在自己的 fork 上跑通第一个 WIP PR。【免费下载链接】prisma1 Database Tools incl. ORM, Migrations and Admin UI (Postgres, MySQL MongoDB) [deprecated]项目地址: https://gitcode.com/gh_mirrors/pr/prisma1创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
