开发工具Lint格式化静态分析代码质量前端【免费下载链接】biomeA toolchain for web projects, aimed to provide functionalities to maintain them. Biome offers formatter and linter, usable via CLI and LSP.项目地址https://gitcode.com/gh_mirrors/bi/biome点击查看免费下载导读Changeset 是 Biome 仓库中用于描述对用户可见行为变化的轻量发布说明文件它决定了下一次CHANGELOG.md与各 npm 包版本号的生成结果。本文以 Biome 仓库中的 changeset skill 为骨架结合 AGENTS.md、CONTRIBUTING.md、justfile 以及 .changeset 目录 下的真实示例完整讲解是否需要 changeset → 如何选择版本级别 → 如何创建文件 → 如何撰写条目 → 如何自查的全流程。读者尤其是为 Biome 提交 PR 的开发者或编码 Agent读完后将能独立、规范地为一个用户可见的变更产出合格的 changeset。一、什么是 Changeset它在 Biome 中扮演什么角色Changeset 描述的是用户可见的行为其最终产物是发布说明release notes。在 Biome 仓库中它由 changesets 工具链驱动负责自动化三件事生成 Biome 二进制、JavaScript 库的版本号为每个库生成对应的CHANGELOG.md汇总所有待发布变更。从 CONTRIBUTING.md 第 428–430 行的描述可以看到仓库明确使用 changesets 来自动化 Biome 二进制与 JavaScript 库的发布以及为每个库生成CHANGELOG.md。也就是说changeset 是连接代码提交与版本发布之间的唯一正式通道PR 描述、代码注释都不能替代它。与其它文档的分工skill 文档开头便点明了三层职责划分理解这一点能避免把 changeset 写成实现细节说明文档职责AGENTS.md定义何时需要 changeset用户可见行为判定CONTRIBUTING.md定义怎样写包选择、版本规则、分支目标、措辞格式是其规范权威来源本 skill面向编码 Agent 的操作指引涵盖判定、选级、创建、撰写与自查仓库根目录的 AGENTS.md 第 55–57 行印证了这一分工用户可见行为必须写 changeset而内部重构、纯测试、CI/构建维护、仅文档修改则不需要对于用户可见的变更应加载本 skill 来选择发布级别并创建/编辑条目。二、第一步判定是否需要 Changeset必须写 changeset 的场景只要行为对以下对象的使用者可见就必须写 changesetCLI命令行工具库JavaScript 库 / 发布出去的 crates诊断输出diagnosticsparser解析器formatter格式化器linter检查器assists辅助操作不需要写 changeset 的场景内部重构且行为完全不变仅新增/修改测试CI 或构建系统维护仅文档修改。关键原则不要从改动文件反推可见性skill 特别强调开 PR 之前必须显式确认该变更的用户可见分类user-facing classification而不能仅凭改动文件推断用户可见性。例如改了某个.rs源码文件不等于对用户可见必须落到行为层面判断这条变更是否改变了用户能感知到的解析、格式化、检查或命令行输出。实际场景中同一处源码改动可能既包含行为修复又包含内部重构判定时应以用户可感知的行为增量为准这正是 AGENTS.md 要求显式确认分类的原因。三、第二步选择发布级别Release LevelBiome 对biomejs/biome主包的版本级别非常严格CONTRIBUTING.md 第 464 行起有更细的说明skill 给出了速查表变更类型级别目标分支缺陷修复或非破坏性行为修正patchmain新增 nursery lint 规则patchmain新增用户可见功能或 nursery 规则晋升minornext破坏性用户 API 变更majornext需要特别注意的两点nursery 规则是特例新增 nursery 规则虽然属于新功能但映射到patch而不是minor原因是 nursery 规则不遵循语义化版本semantic versioning规则。遇到非常规情况应以当前的版本策略为准详见 CONTRIBUTING.md 与官方 versioning 页面。分支目标选minor或major时PR 必须指向next分支而非mainpatch指向main。版本级别与分支必须保持一致这是自查清单中的硬性检查项。从版本哲学的层面看这个映射遵循 CONTRIBUTING.md 第 464–469 行的通用原则patch是任何修复 bug 的变更minor是用户可用的新功能major是破坏用户 API 的变更。四、第三步创建 Changeset 文件推荐方式使用命令生成不要手写skill 与 CONTRIBUTING.md 均强调不要手动创建 changeset 文件而应通过命令生成# 交互式选择包、变更级别并输入描述描述会作为文件名 just new-changeset # 非交互式直接生成一个空文件 just new-changeset-empty这两条命令在 justfile 中定义底层调用 pnpmnew-changeset: pnpm changeset new-changeset-empty: pnpm changeset --empty运行前需要保证仓库根目录已经执行过pnpm installCONTRIBUTING.md 第 440 行的 NOTE 明确说明脚本底层使用 pnpm。生成的 changeset 会出现在.changeset目录下文件名通常是由 changesets 工具随机生成的短语例如仓库中现有的 brave-deer-begin.md、eighty-parents-shake.md。你可以随后打开文件补充更多信息。空文件的 frontmatter 处理just new-changeset-empty生成的空文件会自带一组 frontmatter 分隔符---。此时应该用包名与发布级别替换这组 frontmatter而不是在文件里再追加第二组 frontmatter——一个 changeset 文件只能有一组合法的 frontmatter--- biomejs/biome: patch --- Description.选择正确的包绝大多数情况下选择biomejs/biome主包即可CONTRIBUTING.md 第 448–450 行。仓库的 .changeset/config.json 展示了版本联动fixed关系biomejs/biome与各平台 CLI 包cli-win32-x64、cli-darwin-arm64、wasm-web等 12 个包被固定为一组任一成员升级时整组同步升级保证主包与二进制分发包的版本始终一致。长条目的标题层级约束如果条目内容较长需要加小标题只能使用####或#####。其它层级的标题会干扰 changelog 生成甚至破坏上游工具——这是 CONTRIBUTING.md 第 446 行与 skill 文档共同强调的硬约束。五、第四步撰写 Changeset 条目措辞总原则描述用户可见行为而不是实现细节。不复制 PR 摘要不包含测试计划、内部设计或 reviewer 意见——changeset 是发布说明文本1 到 3 句话除非影响确实需要示例否则保持精简。过长的 changeset 会向用户传递这个变更很重要的信号所以只在你认为用户确实该关注时写长时态规范描述本次贡献用过去时如 Added ...、Fixed ...描述 Biome 行为用现在时如 Biome now supports ...以句号结尾每句话都要以.结束bug 修复以关联 issue 开头例如Fixed [#11351](https://github.com/biomejs/biome/issues/11351): ...规则与 assist 名称链接到 Biome 官网页面即使网站当时尚未更新PR 合并后链接即生效。按变更类型选择示例形式只包含理解影响所必需的那个示例变更类型示例形式新增 lint 规则一个触发规则的无效invalid示例简单场景用行内代码复杂场景用代码块必要时可补充有效示例修改既有规则明确展示现在什么变得无效/有效最好同时给出无效与有效两种示例formatter 变更用diff代码块展示格式化前后的差异parser 变更简短行内示例说明现在能解析或不再能解析什么多行更清晰时用代码块真实示例剖析仓库 .changeset 目录下的条目可以直接对照学习。例如 brave-deer-begin.mdbug 修复类--- biomejs/biome: patch --- Fixed [#11351](https://github.com/biomejs/biome/issues/11351): [useSimplifiedLogicExpression](https://biomejs.dev/linter/rules/use-simplified-logic-expression/) no longer reports boolean literals on the right side of || and outside boolean contexts, because removing them can change the result of the expression. For example, y x || false is no longer reported, while if (x || false) still is.这段完全符合全部规范patch级别、issue 开头、过去时 现在时搭配、链接规则页面、句号结尾并用行内示例交代了现在什么不再被报告、什么仍然被报告。再如 add-no-react-object-type-as-default-prop.md新 nursery 规则类--- biomejs/biome: patch --- Added the new nursery rule [noReactObjectTypeAsDefaultProp](https://biomejs.dev/linter/rules/no-react-object-type-as-default-prop/), which disallows array, object, and function values as default props in React components. For example, the following snippet triggers the rule. jsx function Component({ items [] }) { return items; }注意它同样使用 patch 级别印证新增 nursery 规则 patch的映射包含规则链接、一句话行为描述和一个无效示例。 --- ## 六、第五步Review 自查清单 提交 PR 前对照以下清单逐项检查 changeset这也是 skill 文档给出的最终检查项 - [ ] 行为是用户可见的 - [ ] 包名package选择正确 - [ ] 发布级别与分支策略一致patch→mainminor/major→next - [ ] 描述与实际实现的行为一致 - [ ] issue、规则、assist 链接准确无误 - [ ] 示例展示了可观察的影响invalid/valid、diff、可解析语法 - [ ] 文件只有一个合法的 frontmatter 块不要出现两组 ---。 --- ## 七、从 Changeset 到发布仓库中的落地证据 理解 changeset 的完整生命周期有助于写得更准确。仓库中有三处关键证据 1. **配置文件**[.changeset/config.json](https://link.gitcode.com/i/4774534f6a507adc1e3a19e9591a0c52) 声明了 changelog 生成器changesets/changelog-github repo: biomejs/biome、fixed 包组、access: public、baseBranch: main 以及被忽略的包列表如 biomejs/aria-data、biomejs/runtime、tailwindcss-config-analyzer、biomejs/prettier-compare。被忽略的包不会参与版本联动这也解释了为什么这些工具包无需逐条写 changeset。 2. **目录状态**仓库根目录 [.changeset](https://link.gitcode.com/i/0557124548d8fa3e0a1f0d9c3811f96a) 下同时存在多个待发布条目add-*.md、naming-convention-*.md、nested-alias-inference.md 等每个文件代表一个独立 PR 的用户可见变更会在下次发版时被合并进 CHANGELOG.md。 3. **生成命令**[justfile](https://link.gitcode.com/i/4b47f281c61376140a41e4c59f0ad8a7#L351-L357) 中 new-changeset交互式与 new-changeset-empty非交互式两条 recipe 直接封装 pnpm changeset是创建文件的唯一推荐入口。 从这些证据可以推断Biome 的发布流程是每个用户可见 PR 一条 changeset → 发版时 changesets 工具批量消费 .changeset/*.md → 生成各包版本号与 CHANGELOG.md → 发布 npm 包与各平台二进制。因此changeset 的质量直接决定了用户读到的发布说明质量这也是本 skill 要求描述用户可见行为、不写实现细节的根本原因。 --- ## 附速查总结 | 环节 | 要点 | 仓库依据 | | --- | --- | --- | | 是否需要 | 仅用户可见行为需要内部重构/测试/CI/文档不需要 | [AGENTS.md](https://link.gitcode.com/i/de1a8706bbc160894141347058eeb983#L55-L57)、本 skill | | 版本级别 | bug 修复 新 nursery 规则 patch新功能/nursery 晋升 minor破坏性 API major | 本 skill 速查表、[CONTRIBUTING.md](https://link.gitcode.com/i/c070e154f32f75420dcea1fe3cef2824) | | 目标分支 | patch → mainminor/major → next | [CONTRIBUTING.md](https://link.gitcode.com/i/c070e154f32f75420dcea1fe3cef2824) | | 创建命令 | just new-changeset / just new-changeset-empty底层 pnpm changeset | [justfile](https://link.gitcode.com/i/4b47f281c61376140a41e4c59f0ad8a7#L351-L357) | | frontmatter | 只能有一组用包名 级别替换空文件自带的分隔符 | 本 skill、真实示例 | | 标题层级 | 只用 #### / ##### | [CONTRIBUTING.md](https://link.gitcode.com/i/c070e154f32f75420dcea1fe3cef2824) | | 措辞 | 1–3 句、过去时贡献 现在时行为、句号结尾、bug 以 issue 链接开头 | 本 skill、[CONTRIBUTING.md](https://link.gitcode.com/i/c070e154f32f75420dcea1fe3cef2824) | | 示例 | 新规则给 invalid改规则给新旧行为formatter 用 diffparser 给可解析示例 | 本 skill、[.changeset](https://link.gitcode.com/i/0557124548d8fa3e0a1f0d9c3811f96a) 真实条目 | | 自查 | 包名、级别、分支、描述一致性、链接、示例、单一 frontmatter | 本 skill Review Checklist | 按照以上流程产出的 changeset将无缝接入 [.changeset/config.json](https://link.gitcode.com/i/4774534f6a507adc1e3a19e9591a0c52) 所定义的发布管线成为 CHANGELOG.md 中准确、简洁、对用户友好的一行发布说明。赞分享开发工具Lint格式化静态分析代码质量前端【免费下载链接】biomeA toolchain for web projects, aimed to provide functionalities to maintain them. Biome offers formatter and linter, usable via CLI and LSP.项目地址https://gitcode.com/gh_mirrors/bi/biome点击查看免费下载相关推荐Better Auth 发布说明 AI 重写流水线从 changeset 到确定性渲染的完整实现Better Auth 发布说明 AI 重写流水线从 changeset 到确定性渲染的完整实现 导读 Better Auth 是面向 TypeScript认证鉴权后端身份认证编写 Remix 仓库 Change Files.changes 发布说明约定与完整工作流编写 Remix 仓库 Change Files.changes 发布说明约定与完整工作流 导读 本文围绕 Remix 仓库的 make changes 技能后端前端Web框架Aspire 发布说明 API 文档编写指南从 API Diff 到可验证代码示例的完整工作流Aspire 发布说明 API 文档编写指南从 API Diff 到可验证代码示例的完整工作流 导读 本文是面向 Aspire 仓库发布说明Whats N云原生后端微服务可观测性开发工具创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考