前端【免费下载链接】urqlThe highly customizable and versatile GraphQL client with which you add on features like normalized caching as you grow.项目地址https://gitcode.com/gh_mirrors/ur/urql点击查看免费下载urql是一个高度可定制、灵活的 GraphQL 客户端它的可扩展性不仅体现在运行时通过 exchanges 机制叠加能力如规范化缓存也体现在其开源协作流程上一个基于 pnpm 的 monorepo、以 changeset 驱动的版本管理与半自动化发布。本文以仓库根目录的 CONTRIBUTING.md 为骨架结合仓库内的package.json、pnpm-workspace.yaml、.changeset配置与 .github/workflows/release.yml 等真实文件系统讲解如何向 urql 提交 Issue、发起 RFC、搭建开发环境、运行测试与构建、用 changeset 记录变更以及如何按规范新增一个包。读完你即可独立完成一次从改动到 PR、再到进入发布流水线的完整贡献流程。贡献前的协作约定先沟通再动手urql 团队对贡献者没有严格的流程约束但有一条清晰的协作主线问题去 Discussions、缺陷开 Issue、新功能走 RFC、动手改开 PR。有疑问时优先发起 GitHub Discussions 讨论怀疑是 bug 时打开新 Issue想修复某个已知 bug可以直接开 PR想提议一个新功能或行为变更则应当提交 RFC IssueRFC: Your Proposal标题模板完整的 RFC 模板位于 .github/ISSUE_TEMPLATE/RFC.md要求填写 Summary、Proposed Solution 与可选的 Requirements 三个部分帮助提案者把改什么、为什么现在改、怎么实现说清楚。所有 RFC 会被收录到 RFC Lifecycle 看板中跟踪状态从 In Discussion 逐步推进到可实施。这个环节可能很短、被跳过也可能很长——如果该变更还没有明确的计划团队会欢迎任何人在讨论中提出建议。Issue 的约定解释期望与实际Issue 侧没有严格约定但内置了两个模板bug 报告模板位于 .github/ISSUE_TEMPLATE/bug_report.yaml。经验法则是尽量讲清楚你期望发生什么和实际发生了什么这样维护者能快速判断这是已知行为、意外缺陷还是文档未覆盖的怪癖。团队也明确不鼓励把这些问题开成 Issue纯提问、以及极可能由误用或错误配置导致的 bug。如果你无法提供一个可复现的最小示例那很可能你遇到的其实是提问而非 bug——复现模板可以直接基于仓库examples/目录中的示例项目改造它们是隔离的沙箱项目可独立修改运行。PR 的约定模板 命名PR 同样没有严格约束但需要比 Issue 更严格地遵循 PR 模板见 .github/PULL_REQUEST_TEMPLATE.md模板要求列出Summary变更动机与解决什么问题和Set of changes改了哪些文件、影响哪些包、是否为破坏性变更。如果 PR 解决某个 Issue请在描述中写Resolve #123让 PR 与 Issue 自动关联PR 标题建议采用(shortcode) - Title的命名格式shortcode 通常是包名如(core)标题用祈使句描述例如(core) - Update X或(core) - Refactor Y。提交后你可能看到 Changeset 机器人留言要求你补充变更说明——这正是下一节要讲的 changeset 机制。搭建开发环境pnpm 驱动的 monorepourql 仓库是一个 pnpm workspace 组织的 monorepopackages/目录下是urql/*主包如urql/core、react-urql、svelte-urqlexchanges/目录下是urql/exchange-*插件包如 auth、graphcache、retry、refocus这一布局由 pnpm-workspace.yaml 声明packages: - packages/* - exchanges/* - !examples/*注意examples/被显式排除——示例项目是相互隔离的独立项目没有锁文件、也不与 monorepo 内的包做链接。安装依赖文档明确要求使用 pnpm 而非 npm 或 yarn以保证锁文件一致pnpm install仓库根目录 package.json 要求 Node 18、pnpm 9安装完成后postinstall钩子会执行 scripts/prepare/postinstall.js 做环境校验。根目录的四个常用命令在仓库根目录可以运行以下命令验证改动对应 package.json 的 scripts# TypeScript 类型检查全部包 pnpm run check # 代码规范检查prettier eslint pnpm run lint # 单元测试全部包 pnpm run test # 构建全部包 pnpm run build从源码看这些脚本分别落到tsc、eslint --extjs,jsx,ts,tsx .、vitest与node ./scripts/actions/build-all.mjs。各包内部还有一套完全一致的同名脚本用于只针对当前包运行# 当前包的单元测试 pnpm run test # 当前包的 lint pnpm run lint # 构建当前包 pnpm run build # 当前包的 TypeScript 检查 pnpm run check以 packages/core/package.json 为例其脚本定义就是vitest、tsc --noEmit、eslint与rollup -c ../../scripts/rollup/config.mjs。文档特别提醒出于时间考虑尽量只构建你正在改动的包而checkTypeScript 检查不依赖任何包先被构建可以放心全局运行。如何验证你的改动测试与示例改完代码后最稳妥的做法是在仓库根目录运行pnpm test覆盖所有可能受影响的包。如果你用的编辑器没有接入类型检查建议再补跑pnpm run check。更贴近真实场景的验证方式是使用examples/下的示例项目。这些示例如 examples/with-react、examples/with-next、examples/with-vue3、examples/with-graphcache-pagination 等覆盖了 React、Preact、Vue、Solid、Svelte、React Native 以及 APQ、Multipart、订阅、Graphcache 分页、认证刷新、重试等典型场景。由于它们不链接 monorepo 内包需要单独安装依赖然后通过各自package.json中的start脚本启动。例如cd examples/with-react pnpm install pnpm start如果编辑器未配置 prettier/eslint代码风格校验由仓库的precommit钩子兜底——它由 husky 驱动、调用lint-staged见 package.json 中的lint-staged配置会在提交前自动修复格式问题或直接报错提示你处理。用 changeset 记录每一次可见变更urql 的版本管理基于changesets工具。规则很简单每个 PR 都必须附带一份变更文档说明改了什么、影响哪个包。生成方式是在仓库根目录运行pnpm changeset交互式命令会依次询问哪些包发生了变更、这次变更属于 major / minor / patch 哪一档然后引导你以 Markdown 写入变更描述。生成的 changeset 文件 存放在.changeset/目录中仓库现有配置见 .changeset/config.json它指定了 changelog 生成脚本 scripts/changesets/changelog.js你需要把它提交并推送进 PR。哪些情况不需要changeset文档明确只涉及文档、或其他不会发布到 npm registry 的不可见改动就无需添加。这些 changeset 最终会在发布时被聚合进各包的CHANGELOG.md——例如 packages/core/CHANGELOG.md 就是由该机制持续生成的版本历史。发布流程全自动只留一道审批门版本发布完全自动化核心链路记录在 .github/workflows/release.yml每当有改动合并到main分支Release 工作流被触发changesets 工具生成并持续更新一个Version Packages PRPR 描述中会预览所有包即将写入的新 changelog当该 PR 被维护者批准并合并后流水线在npm环境审批门environment: npm处暂停等待人工确认审批通过后动作自动完成发布——把更新后的包发布到 npm registry并在 GitHub 上打对应 tag。发布前可以用pnpm changeset status预览当前批次将产生的版本变化。同时注意合并前务必人工检查 changelog 内容是否有错误。至于何时合并发布 PR文档给出两条经验法则hotfix热修复如果某个 bug 对用户有负面影响应尽快单独发出去release batch发布批次如果某个包刚有一处改动通常同一周内还会有更多改动跟进因此等一两天再合并发布可以显著降低下游维护者的更新负担。升级依赖pnpm update 与去重urql 仓库会定期统一升级依赖。推荐做法是pnpm update --interactive --latest逐条确认需要升级的依赖。出现安全问题时也可以针对单个包运行pnpm update [package]。升级传递依赖偶尔会导致同一依赖被重复安装两个包依赖了不同的兼容版本区间此时用pnpm-deduplicate去重npx pnpm-deduplicate pnpm install如果升级涉及dependencies变化记得照常开一个 PR并用 changeset 记录受影响包PR 标题可以命名为(chore) - Upgrade direct and transitive dependencies之类。新增一个包目录、命名与构建约定先决定放哪里Exchange 插件放exchanges/文件夹名直接用 exchange 的简短名称不含urql/exchange-前缀例如现有exchanges/auth、exchanges/graphcache、exchanges/retry其他包放packages/通常命名为urql/*文件夹名去掉前缀如果包名以*-urql结尾如svelte-urql文件夹可以直接同名。从复制 package.json 开始文档建议从其他包复制一份package.json作为起点然后依次修改nameversion从0.1.0或1.0.0起步descriptionrepository.directorykeywords同时按需调整devDependencies、peerDependencies与dependencies。main / module / types 的命名约定这是新增包时最容易踩坑的约定。所有输出统一由 rollup 写入./dist目录构建脚本见 scripts/rollup/config.mjs文件名为name字段的 kebab-case短横线命名形式并按用途加扩展名module字段 →.esm.jsESM 产物如urql/core的dist/urql-core.mjsmain字段 →.cjs.jsCJS 产物如dist/urql-core.jstypes字段必须指向dist/types目录下与入口文件对应的 TypeScript 声明文件如dist/urql-core.d.tsrollup 会负责生成。入口默认是src/index.ts可以按需调整但types字段必须与package.json:source指向的入口保持相对一致。别忘了创建src/index.ts或你在package.json:source里指向的文件从其他包复制tsconfig.json无需修改每个包的scripts.prepare都会用 scripts/prepare/index.js 校验新的package.json是否正确——写错任何字段运行pnpm时立刻会收到简短报错。搭建完成后用下面的命令验证一切正常pnpm install pnpm run check发布权限文档特别提醒不要自行发布这个新包除非不得已。新包需要加入urql的 npm scope由维护者授予权限通常执行npm access grant read-write urql:developers [package]小结urql 的贡献流程可以概括为宽松的规范 自动化的兜底协作上先 Discussions / Issue / RFC 对齐意图PR 遵循模板与(shortcode) - Title命名工程上用 pnpm 统一安装与脚本check/lint/test/build靠 precommit 钩子守住代码风格每个可见变更必须经pnpm changeset记录最终由 .github/workflows/release.yml 自动汇聚 changelog、打开 Version Packages PR并在npm审批门后完成发布。这套机制既保证了urql可扩展、可定制理念的持续演进也让外部贡献者能够以最小摩擦进入主流程——无论你贡献的是一行文档修正还是一个全新的 exchange 包。赞分享前端【免费下载链接】urqlThe highly customizable and versatile GraphQL client with which you add on features like normalized caching as you grow.项目地址https://gitcode.com/gh_mirrors/ur/urql点击查看免费下载相关推荐TinaCMS 贡献指南从本地开发环境搭建到 changeset 发布全流程实战TinaCMS 贡献指南从本地开发环境搭建到 changeset 发布全流程实战 TinaCMS 是一个以 Markdown 与可视化编辑为核心的开源 HeaCMS前端后端GraphQLbook-to-skill 贡献指南从开发环境搭建到 git-cliff 发布流程的完整实践book to skill 贡献指南从开发环境搭建到 git cliff 发布流程的完整实践 导读 本文围绕开源项目 book to skill 的贡献规范AI 技能Spectacle 贡献指南从本地开发环境搭建到 Changeset 版本管理与发布全流程Spectacle 贡献指南从本地开发环境搭建到 Changeset 版本管理与发布全流程 Spectacle 是一个基于 React、使用 JSX 语法创建前端UI组件上一篇InternVL训练脚本逐行解析internvl_chat_finetune.py代码全解下一篇openEuler安全委员会完全指南如何保障开源操作系统的供应链安全创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
