这是一个面向 Shopify Hydrogen 仓库贡献者的 Pull Request 描述写作技能。其核心用途是帮助评审者快速理解一次改动的内容、意图和影响,让 PR 描述具备功能性而非只罗列代码差异。创建或更新 PR 描述时均可使用。
主要能力体现在对写作风格与结构的规范。风格上,要求使用短段落、清晰的小标题和要点,语言简单易懂,避免复杂行话;仅对重要内容加粗;具体而简洁;不追求吸睛、俏皮、商业化或发布宣传式的语气;不包含完整 diff,只突出本 PR 触及的部分。
结构上,第一个部分说明 PR 的动机(Why),无需标题;若 PR 关闭某个 issue,在开头提及。随后按实际情况选用:TL;DR 简述问题与意图;Before/After 用最小可用的旧/新代码或行为对比;What this changes 列出具体改动;Developer impact 仅在涉及库使用者、示例、公共导出、包内技能、类型或迁移路径时出现;UX impact 仅在涉及路由、按钮、UI 状态、表单、导航、文案、加载状态或无障碍行为时出现;Out of scope 说明本 PR 有意不解决的问题,而非路线图;Risk 说明可能出问题之处、已知取舍或需额外审查的点;How to Test 给出面向人工的手动验证步骤。不适用的类别不应保留。
写之前需先识别意图,可来自对话上下文、issue、规格、关联 PR、评审线程或任务笔记,并结合目标分支与本 PR 的 diff。还需梳理开发者影响、UX 影响、前后对比、是否需要 changeset、人工测试流程,以及范围与风险边界。若从 diff、issue、规格、关联 PR、评审线程或当前对话中仍无法明确动机,应先询问用户再起草。
在版本管理方面,若 diff 触及 packages/hydrogen/src/、包导出、packages/hydrogen/skills/ 或用于示范受支持模式的示例,需说明是否包含 changeset 及为何是该级别。级别划分为:patch 适用于缺陷修复、内部重构或无新公共 API 的技能/示例加固;minor 适用于新增导出、辅助函数或对使用方增量式的受支持模式;major 适用于公共导出或受教模式的破坏性变更。由于 Hydrogen 采用 CalVer 版本号,这些级别不会直接映射到版本号,发布时由脚本转换;处于预发布期时 CI 会拒绝 major changeset。无需 changeset 时应说明原因。
人工测试部分要求面向人工在本地手动验证,默认按 MacBook 环境,列出执行该行为所需的每一步,包括安装与构建、启动示例应用、打开页面、执行操作并确认结果等。lint、类型检查、单元测试、集成测试或 CI 不得作为 How to Test 的内容;若没有有意义的手动行为可测,则省略该节。
使用限制与规范还包括:不得只写 diff 摘要;不得保留不适用的标题;不得把开发者或 UX 影响藏在实现细节的要点里;不得在 What this changes 中描述无关的未来工作;不得过度解释 TypeScript 或 diff 已显而易见的内容;API 与示例迁移时使用简短聚焦的前后片段;把面向开发者的影响与实现细节分开;公共入口点变更应与内部重构分开说明。
本资料未提供该技能的具体安装命令、工具形态或收费信息,暂未提供。