Jotai 贡献指南：从 Issue 报告到 Pull Request 提交的完整开发工作流-平芜编程栈

前端
状态管理

【免费下载链接】jotai

👻 Primitive and flexible state management for React

项目地址：https://gitcode.com/gh_mirrors/jo/jotai

Jotai 是一个面向 React 的原始且灵活的状态管理库，其仓库（当前版本 2.20.2，MIT 许可）由src/（核心实现）、tests/（测试）、docs/（文档源）与website/（Gatsby 文档站点）等模块组成。本篇指南以仓库根目录下的 CONTRIBUTING.md 为骨架，结合 package.json、vitest.config.mts、rollup.config.mjs、website/gatsby-config.js 等真实配置文件，完整梳理从报告问题、提交规范、编写失败测试、构建验证到提交 Pull Request 的每一步，帮助你以符合项目预期的方式为 Jotai 贡献代码或文档。

一、仓库结构速览：贡献者需要先知道的关键目录

在动手之前，先了解仓库的目录组织，这会直接影响测试与文档改动的位置：

src/：全部核心源码，分为三个子包——vanilla/（与框架无关的状态核心，含 atom.ts、store.ts、internals.ts 及utils/下的 atomFamily、selectAtom、splitAtom 等工具）、react/（React 绑定，含 useAtom、useAtomValue、useSetAtom 及utils/）、babel/（babel 插件与预设，如 plugin-debug-label、plugin-react-refresh）。
tests/：测试目录，与src/一一对应（tests/vanilla、tests/react、tests/babel）。
docs/：文档源文件（MDX 格式），按basics/、core/、guides/、recipes/、utilities/、extensions/等分类组织。
website/：基于 Gatsby 的官方文档站点工程。
examples/ 与 benchmarks/：示例项目与性能基准，可用于验证改动。
rollup.config.mjs、vitest.config.mts、eslint.config.mjs、babel.config.mjs：构建、测试、代码检查与转译配置。

二、报告问题与发起讨论：Issue 之前的必经步骤

Jotai 的贡献规范要求：一切问题与功能建议都先从 GitHub Discussions 的讨论开始，而不是直接提交 Issue。根据 CONTRIBUTING.md 的约定，讨论按类别分流：

场景	讨论类别	预期结果
怀疑发现了 bug	`bug-report`	在讨论中确认问题表现与复现路径
使用上的疑问	`q-a`	获得社区与维护者的解答
新功能建议	`ideas`	先讨论该功能的使用场景，再讨论具体实现方案

对于新功能，文档明确要求先确认讨论区中是否已存在同类提议；若不存在，则发起ideas讨论。维护者会基于讨论确认用例是否成立，进而敲定实现方式——这意味着功能贡献的代码工作应在讨论收敛之后开始，避免方向偏差造成返工。

三、提交规范：遵循 Conventional Commits

Jotai 严格采用 Conventional Commits 规范（即"约定式提交"），每一次提交的 type 必须是以下六种之一：

提交类型	含义
`feat`	新增功能
`fix`	修复 bug
`refactor`	既不修复 bug 也不新增功能的代码改动
`chore`	构建流程、配置、依赖、CI/CD 管道等辅助工具的改动
`docs`	仅涉及文档的改动
`test`	补充缺失的测试或修正现有测试

格式要点：type 作为提交信息的第一个单词，后跟冒号与空格，描述以小写字母开头：

feat: add a 'foo' type support

还可以在 type 后使用括号指定作用域（scope）：

fix(react): change the 'bar' parameter type

结合本仓库的源码组织，作用域通常可以对应到具体子包，例如vanilla、react、babel，或docs、website等。规范化的提交信息不仅便于维护者快速审阅 PR，也让 CHANGELOG 的生成与版本发布自动化成为可能。

四、开发工作流总览（General）

无论贡献代码还是文档，主流程一致：

Fork 本仓库。
基于main分支创建新的功能分支。
依据下面"核心代码贡献"或"文档贡献"部分完成开发。
运行pnpm run fix:format格式化代码。
暂存改动并提交（遵循上文提交规范）。
提交 Pull Request 等待评审。

其中格式化环节在 package.json 中的定义是prettier . --write，即对整个仓库执行 Prettier 写回。仓库为 Prettier 配置了semi: false（不加分号）与singleQuote: true（单引号），提交前务必执行以确保风格一致。与之配套的还有两个相关命令：

pnpm run fix:lint：执行eslint . --fix自动修复可修复的 lint 问题；
pnpm run fix：依次执行 lint 修复与格式修复（fix:lint+fix:format）。

从 eslint.config.mjs 可以看到，仓库使用 ESLint 的 flat config，启用了eqeqeq、curly、sort-imports、import/order（按 builtin/external/internal/parent/sibling/index 分组并字母序排列）等规则；对tests/**目录额外启用了 vitest、testing-library、jest-dom 三套插件，且测试文件中import/extensions被设为never（即测试内导入不写扩展名），而普通源码要求显式扩展名。

五、核心代码贡献（Core）：六步完成一次代码改动

1. 安装依赖：pnpm install

在仓库根目录执行pnpm install。项目使用 pnpm workspace 管理，pnpm-workspace.yaml 声明了两个包：根目录（.）与website。同时 package.json 通过packageManager: "pnpm@11.3.0"锁定包管理器版本（可配合 corepack 使用），环境要求 Node.js>=12.20.0。

2. 为你的修复或新功能编写失败测试

这是核心贡献流程中最先动手的一步——先写会失败的测试，再实现代码，确保改动有测试覆盖。

测试文件放在 tests/ 目录，命名约定为：纯逻辑测试用.test.ts（如 tests/vanilla/utils/atomFamily.test.ts），涉及 React 渲染的用.test.tsx（如 tests/vanilla/basic.test.tsx、tests/react/basic.test.tsx）。测试基础设施由 vitest.config.mts 定义：

测试环境为jsdom，并开启globals（同时触发 React Testing Library 的自动 cleanup）；
通过 alias 将jotai与jotai/xxx直接指向 src/index.ts 等源码文件，因此测试中可以直接写import { atom } from 'jotai/vanilla'来测试未构建的源码；
tests/setup.ts 引入@testing-library/jest-dom/vitest，提供 jest-dom 的自定义断言。

例如 tests/vanilla/basic.test.tsx 展示了atom()的四种创建形式：原始 atom、只读派生 atom、读写派生 atom 与只写派生 atom，可作为编写新测试的模板参考。测试还覆盖了异步（tests/react/async.test.tsx）、依赖追踪（tests/react/dependency.test.tsx）、错误处理（tests/react/error.test.tsx）、内存泄漏（tests/vanilla/memoryleaks.test.ts）等专题，新功能若涉及相应领域，可在对应专题文件中补充用例。

3. 实现你的改动

在 src/ 对应子包中实现功能或修复。核心 API 的入口文件是 src/index.ts（聚合 React 绑定）、src/vanilla.ts 与 src/utils.ts，子包内的工具函数位于各utils/目录。

4. 构建库：pnpm run build

pnpm run build是完整的发布前构建。从 package.json 的脚本定义看，它依次执行：

prebuild：shx rm -rf dist清空旧产物；
build:*：并行运行全部子构建，包括build:base（主入口，rollup -c）、build:vanilla、build:vanilla:utils、build:vanilla:internals、build:react、build:react:utils、build:utils、build:babel:plugin-debug-label、build:babel:plugin-react-refresh、build:babel:preset等；
postbuild：依次执行patch-d-ts（修正声明文件中的导入路径）、copy（复制产物并生成 ts3.8 兼容类型与 ESM 声明）、patch-ts3.8、patch-old-ts、patch-esm-ts、patch-readme等收尾脚本。

构建配置集中在 rollup.config.mjs，为每个入口产出 CJS（dist/*.js）、ESM（dist/esm/*.mjs）、UMD（dist/umd/*.development.js与*.production.js，生产版经 terser 压缩）以及 SystemJS（dist/system/*）共多种格式，并为 React 相关产物注入'use client'指令。

提示：如果只想在改动后持续监听并重新构建，文档推荐使用pnpm run build-watch（即pnpm run "/^build:.*/" --watch），它会在 watch 模式下运行全部子构建，适合边改边验。

5. 运行测试并确保全部通过

执行pnpm run test。该命令会依次运行（pnpm run "/^test:.*/"）：

test:format：prettier . --list-different，检查格式是否一致（不通过说明需要先跑fix:format）；
test:types：tsc --noEmit，基于 tsconfig.json 做全量类型检查；
test:lint：eslint .，静态代码检查；
test:spec：vitest run，运行全部单元与集成测试。

四者全部通过才算测试就绪。若改动涉及性能敏感路径，仓库还提供pnpm run bench（npx tsx benchmarks/run-all.ts）运行 benchmarks/ 下的性能基准，可用于观察改动是否引入明显回归。

6. 本地联调：pnpm link 或 CodeSandbox CI canary

构建与测试通过后，你可以在自己的真实项目中验证改动：

pnpm link：在仓库根目录执行pnpm link将开发中的包注册为全局软链接，然后在目标项目中执行pnpm link jotai（以及需要验证的子路径）即可引用本地版本；
CodeSandbox CI canary：提交 PR 后，CodeSandbox CI 会自动生成 canary 版本，你可以在自己的项目中安装该 canary 版本来验证改动而无需本地链接。

完成以上步骤后，回到"开发工作流总览"的第 4 步继续（格式化 → 提交 → 提 PR）。

六、文档贡献（Documentation）：在本地运行文档站点

Jotai 的文档与代码同仓维护，贡献文档有一套独立的本地预览流程：

进入 website/ 目录（如cd website）；
在该目录执行pnpm install安装站点依赖；
执行pnpm run dev启动开发服务器。根据 website/package.json，该命令实为gatsby develop -H 0.0.0.0 -p 9000，监听所有网卡、端口 9000；
浏览器访问http://localhost:9000查看文档；
修改 docs/ 目录下的文档文件（MDX 格式）；
浏览器会热重载展示你的改动；
完成后回到总览工作流第 4 步（格式化 → 提交 → 提 PR）。

理解站点如何加载文档有助于定位改动位置：website/gatsby-config.js 通过gatsby-source-filesystem将../docs（即仓库根目录的 docs/）注册为文档源，配合gatsby-plugin-mdx将.md/.mdx渲染为页面，并用 Algolia 建立全文搜索索引（website/gatsby-config.js 中的 DOCS_QUERY 会抓取每篇文档的标题、description、keywords、H2 标题与正文）。文档内容的组织方式可参考 docs/index.mdx 与 docs/core/atom.mdx 等既有页面，保持风格与 API 描述的一致性。

七、Pull Request 规范

提交 PR 时注意两点：

保持范围聚焦：尽量让 PR 只解决一个问题，避免混入无关提交，这能显著加快评审速度；
勾选 "Allow edits from maintainers"：文档建议在 PR 页面勾选"允许维护者编辑"，这样维护者可以直接在你的分支上做出小幅修正或补充，减少来回沟通成本。

提交后维护者会尽快响应，过程中可能建议调整或要求改进，届时在 PR 讨论中继续协作即可。

结语

整个贡献流程可以浓缩为一条主线：先讨论、后实现、测试先行、构建验证、规范提交。无论你打算修复 src/ 中的核心逻辑、补充 tests/ 下的测试用例，还是完善 docs/ 中的文档章节，遵循 CONTRIBUTING.md 中描述的讨论分流、Conventional Commits 提交规范与 Core/Documentation 两套开发流程，都能让改动更快地被维护者接纳。从一条fix: ...或docs: ...的规范提交开始，你就已经进入了 Jotai 的协作节奏。