开发工具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点击查看免费下载本文基于 Biome 仓库根目录的 CONTRIBUTING.md 撰写并结合仓库中的 justfile、rust-toolchain.toml、Cargo.toml、.changeset 等工程文件进行源码级印证与扩充。读完本文你将掌握在 Biome 仓库中搭建本地开发环境、编写与测试代码尤其是 lint 规则与解析器/格式化器、通过代码生成与静态检查、按 Conventional Commits 规范提交、创建带 changeset 的 PR以及理解团队分支策略与版本发布机制的完整路径。前言为 Biome 贡献代码前需要了解的事Biome 是一套面向 Web 项目的工具链提供格式化器formatter与 linter可通过 CLI 与 LSP 使用。仓库根目录的 CONTRIBUTING.md 是社区贡献的官方入口文档它覆盖了从提问与报 bug到本地开发、测试、调试、构建、代码检查、子 crate 开发、依赖管理、Node.js 开发、提交规范、PR 流程、changeset、版本发布的完整链路。在动手写代码之前有几个关键认知需要建立项目形态这是一个 Rust workspace见 Cargo.tomlmembers [crates/*, ...]所有核心工具链实现以biome_*命名平铺在crates/目录下每个子 crate 对应一门语言或一个子系统parser、formatter、analyze、syntax、factory 等。工具链要求构建需要stableRust 工具链仓库通过 rust-toolchain.toml 固定了channel 1.98.1与profile default并预设了wasm32-unknown-unknown目标以及just、pnpm等辅助工具。代码生成是常态Biome 大量使用 codegenxtask_codegen生成代码CI 会校验生成结果与提交是否同步因此改完代码要跑对应 codegen是贡献流程中的硬性环节。AI 辅助披露规则AI assistance notice这是 Biome 贡献流程中相当独特的一条规则只要你在贡献中使用了任何形式的 AI 辅助就必须在 PR 中披露。文档要求披露使用范围例如This PR was written primarily by Claude Code. I consulted ChatGPT to understand the codebase but the solution was fully authored manually by myself.披露的目的在于帮助 reviewer 理解 PR 的上下文、施加适当的审查力度。同时文档明确强调不要使用 AI 撰写 PR 描述或贡献者沟通内容维护者审查带宽有限过长或低信号的解释会拖慢审查如果项目认为 AI 生成的沟通内容被使用可能直接关闭 PR反复在评论区争论或重开 PR可能影响该贡献者后续贡献被接受。这条规则的配套体现可见仓库的 .github/PULL_REQUEST_TEMPLATE.md 顶部注释——模板本身就以IMPORTANT!!提示 AI 辅助必须披露。提问、提案与 Bug 报告提问与提案问题、提案或反馈通过 GitHub Discussion 发起要求评论要有价值避免仅为刷存在感的灌水评论即时交流项目 Discord 服务器所有活动仍受 CODE_OF_CONDUCT.md 约束沟通基调维护者利用业余时间维护项目请保持友善。报告 BugBug 统一提交到 GitHub Issues提交前确认该 bug尚未被报告且尚未在 main 分支修复可使用 Playground 在 main 分支上验证也提供官方 CodeSandbox 模板用于快速复现。本地开发环境搭建Getting Started本地开发Local development构建 Biome 需要stableRust 工具链可用 rustup 安装克隆仓库并进入目录git clone https://github.com/biomejs/biome cd biome之后即可用 cargo 以开发模式运行 Biome CLI# 等价于运行 biome --help cargo biome-cli-dev --helpbiome-cli-dev是仓库为开发场景定制的 cargo alias对应crates/biome_cli的biome二进制目标见 crates/biome_cli/Cargo.toml它让开发者无需先cargo build即可直接体验 CLI 行为。安装所需工具Install the required tools项目使用 Just 作为任务运行器来统一脚本与任务。安装方式# 用 cargo 安装 cargo install just # 更推荐使用系统包管理器安装避免每次命令都前缀 cargo安装just后在仓库根目录运行just install-tools该命令会安装工具用途cargo-binstall安装 cargo 的二进制扩展cargo-insta管理仓库内快照测试的 cargo 扩展tombi格式化 TOML 文件的小工具wasm-bindgen-cli、wasm-opt管理 Biome 的 WASM 构建从仓库实际的 justfile 可以看到install-tools的真实内容它依次执行cargo install cargo-binstall、cargo binstall cargo-insta1.48.0 wasm-opt cargo-deny、cargo binstall wasm-bindgen-cli --version 0.2.117和pnpm install其中还额外包含了cargo-deny。也就是说just install-tools同时也完成了 pnpm 依赖的安装。另外还需要在机器上安装pnpm并在仓库根目录运行pnpm install。pnpm主要用于 创建 changeset。注意文档所述的tombi与仓库 tombi.toml 配置文件相呼应用于保持仓库内 TOML 文件格式统一。GitHub Codespaces 方案不想在本地折腾环境可以直接使用项目预配置的 GitHub Codespaces预配置了开发所需的全部工具与依赖开箱即用注意基础版 Codespace32GB 磁盘在构建 biome 或跑完整测试套件时可能磁盘不足因此预配置镜像使用 64GB 磁盘的 premium 镜像。测试、快照与调试Testing用 cargo 快速跑测试# 运行测试 cargo test # 或使用快捷键 cargo t行为规则在仓库根目录运行cargo t会运行整个仓库的所有测试在某个 crate 目录内运行则只运行该 crate的测试cd crates/biome_cli cargo t # 只跑 biome_cli 的测试运行单个测试把测试名跟在test命令后cd crates/biome_js_formatter cargo t quick_test输出类似running 1 test test quick_test::quick_test ... ok test result: ok. 1 passed; 0 failed; 0 ignored; 0 measured; 224 filtered out; finished in 0.02s用 just 跑与 CI 一致的测试just test使用与 CI 相同的测试运行器实际等价于cargo test --no-fail-fast见 justfile测试单个 crate 使用just test-crate biome_cliDoctestRust 有doctest概念写在 doc 注释里的代码块会在测试阶段被真正执行例如/// I am a doc test /// /// assert_eq!(true, true) // 这是 doctest断言必须通过 /// fn some_fn() { }只运行 doctestjust test-doc快照测试与 insta仓库大量使用快照测试多数通过insta完成而insta已在just install-tools中安装好。当快照测试失败时cargo insta accept接受所有变更并更新所有快照cargo insta reject拒绝所有变更cargo insta review逐个审查快照。在仓库中快照测试的产物遍布各 crate 的tests/specs与tests/snapshots目录例如crates/biome_js_analyze/tests/snapshots、crates/biome_cli/tests/snapshotsinsta.yaml则提供了 insta 的仓库级配置。测试时调试Debugging像 JavaScript 的console.log一样Rust 中可以用dbg!()宏在调试时打印fn some_function() - static str { let some_variable some_variable; dbg!(some_variable); some_variable } #[test] fn test_some_function() { let result some_function(); assert_eq!(result, some_variable) }然后给 cargo 传入--show-output查看输出cargo t test_some_function --show-outputDebug 二进制与 Production 二进制Debug 二进制构建开发版二进制对复现问题triage非常有价值——它可以提供 logging、trace logs 等更多信息也用于调试 LSP 客户端相关的问题。从仓库根目录构建cargo build --bin biome产物位于target/debug/biome。调试 CLI 复现把biome二进制拷贝到复现项目根目录并把脚本中调用 npm 包的地方改为调用该二进制{ scripts: { - lint: biome lint, lint: ./biome lint } }调试 LSP 复现确保客户端如 VSCode、Zed支持自定义二进制路径提供绝对路径{ biome.lsp.bin: /Users/john/www/biome/target/debug/biome }使用 debugging profile默认devprofile 会移除编译期调试信息导致堆栈信息stacktrace不可用。需要调试时使用debuggingprofile——它会保留信息重新编译依赖因此可能耗时较长cargo t --profile debugging some_test在仓库根 Cargo.toml 中可以确认[profile.debugging]的定义inherits dev且debug true。同时devprofile 本身被设置为debug line-tables-only、split-debuginfo unpackedCargo.toml这正是文档所说移除调试信息的根源。Production 二进制通常加--release即可但Biome 要求设置环境变量BIOME_VERSION用于在编译期生成不同代码当BIOME_VERSION与0.0.0不同时构建会关闭所有 recommended 的 nursery 规则BIOME_VERSION的具体值无所谓只要不是0.0.0。所以生产构建命令形如BIOME_VERSION0.0.1 cargo build --bin biome --release提交前的检查清单Checks完成工作、准备提交并开 PR 前需要运行just fjust format的别名格式化 Rust 与 TOML 文件justfile 中它实际执行cargo formatpnpm formatjust ljust lint的别名对整个项目运行 linter即cargo lintclippy见 justfile代码生成codegen按你改动的领域选择修改linter相关代码运行just gen-analyzer在workspace相关代码上工作运行just gen-bindings。也可以直接运行just ready它会执行整个仓库的 codegen比较耗时。从 justfile 看ready会依次执行git diff --exit-code --quiet检查工作区干净 →just gen-all全量 codegen→just documentation→just lint→just test→just test-doc→ 再次git diff --exit-code --quiet确认 codegen 没有留下未提交的变更。值得补充的是仓库 Cargo.toml 中通过[workspace.lints.clippy]与[workspace.lints.rust]定义了全 workspace 统一的 lint 级别大量 clippy 规则为warn这正是just l运行时 clippy 的检查依据。Crates 开发Crates development创建新 crate若要在 workspace 内新建 crate使用just new-crate对应 justfile 中的cargo new crates/{{name}} --libcargo new crates/biome_new_crate --lib其中biome_new_crate是新 crate 名--lib表示创建库 crate因此会生成src/lib.rs。Analyzer 与 lint 规则analyzer 的工作原理、如何创建规则、如何编写测试详见仓库内文档 crates/biome_analyze/CONTRIBUTING.md。该文档是 Biome 贡献体系中最核心的技术文档之一覆盖rule 命名规范noConcept/useConcept、rule 分类Syntax / Lint / Assist、declare_lint_rule!宏、rule options、语义模型Semantic Model查询、多个 signals、code actions、快照测试与文档规范等并配合 justfile 中的new-js-lintrule、new-css-lintrule、new-graphql-lintrule等脚手架命令如cargo run -p xtask_codegen -- new-lintrule --kindjs --categorylint --nameRuleName后接just gen-analyzer快速生成规则骨架。从源码结构看规则实现分布在crates/biome_js_analyze/src/lint、crates/biome_css_analyze/src/lint等目录快照测试则位于各自tests/specs下例如crates/biome_js_analyze/tests/specs、crates/biome_css_analyze/tests/specs。Parser解析器的工作原理与测试编写详见 crates/biome_parser/CONTRIBUTING.md。解析器实现分布在crates/biome_js_parser、crates/biome_css_parser、crates/biome_json_parser等 crate 中每种语言还有对应的 ungrammar 语法描述文件如 xtask/codegen/js.ungramcodegen 会基于它们生成 syntax 节点。Formatter格式化器的工作原理与测试编写详见 crates/biome_formatter/CONTRIBUTING.md。格式化器实现分布在crates/biome_js_formatter、crates/biome_css_formatter等 crate 中其测试目录包含大量.prettier-snap文件例如crates/biome_js_formatter/tests/specs下的*.prettier-snap、*.prettier-snap-original用于与 Prettier 行为进行对照。Crate 依赖规范Crate dependencies仓库使用 workspace dependencies许多依赖定义在根 Cargo.toml 的[workspace.dependencies]中从 Cargo.toml 可以看到所有biome_*内部 crate 与外部依赖的统一定义例如insta 1.48.0、wasm-bindgen-cli对应的wasm-bindgen等。关键规则内部 cratebiome_*在[dependencies]下用workspace true加载但[dev-dependencies]下的内部biome_*crate必须使用 path 依赖而非workspace true以避免测试场景下从 registry 解析这些 crate[dependencies] biome_parser { workspace true } # OK: 常规依赖用 workspace true [dev-dependencies] biome_test_utils { path ../biome_test_utils } # 正确 biome_formatter { path ../biome_formatter, features [countme] } # 正确带 features # biome_test_utils { workspace true } # 错误: dev-deps 不要用 workspace所有内部 crate 都作为crates/下的兄弟目录存在因此相对路径恒为../biome_name。这一规范在 crates/biome_cli/Cargo.toml 中有真实体现——其[dev-dependencies]中biome_css_formatter、biome_js_formatter等均使用path ../...形式。Node.js 开发Node.js developmentnpm 模块packages/biomejs/biome包含 Biome 的 Node.js API支持不同后端wasm-nodejsWebAssemblybackend-jsonrpc与 daemon 建立连接。开发和测试需要构建这些包步骤如下安装 pnpm运行just install-tools安装wasm-bindgen-cli和wasm-opt运行pnpm --filter biomejs/backend-jsonrpc build运行pnpm --filter biomejs/js-api build:wasm-dev和pnpm --filter biomejs/js-api build运行pnpm i --filter biomejs/js-api --frozen-lockfile链接 WebAssembly 绑定与 JSON-RPC 绑定。注意测试是针对编译后的文件运行的因此实现功能/修复 bug 后必须重新运行build脚本。对应地仓库 justfile 中提供了build-wasm-bundler、build-wasm-node、build-wasm-web等 WASM 构建任务且packages/biomejs/wasm-bundler、packages/biomejs/wasm-nodejs、packages/biomejs/wasm-web目录正是各目标平台的绑定产物目录。翻译Translations希望参与文档翻译的贡献者请参阅官网翻译贡献指南docs 的 translation contribution guidelines。提交信息规范Commit messagesBiome 团队尽可能遵循 Conventional Commits 规范这有助于提交最佳实践并驱动基于提交的功能如 changelog 生成。支持的提交前缀前缀含义build:影响构建系统或外部依赖的变更chore:项目日常维护ci:影响 CI 的变更docs:文档更新feat:新功能fix:缺陷修复perf:性能优化refactor:不改变功能的代码重构release:新版本发布revert:回退之前的变更test:测试更新规范示例feat(compiler): implement parsing for new type of files fix: fix nasty unhandled error docs: fix link to website page test(lint): add more cases to handle invalid rules项目使用 action-semantic-pull-request。创建 Pull RequestCreating pull requests新建 PR 时建议使用 conventional commit 格式的标题因为合并squash后该标题会成为默认提交信息。分支策略如下修复 bug代码或文档发 PR 到维护分支main新增 nursery 规则发 PR 到mainnursery 规则不遵循语义化版本将规则从 nursery 提升promote发 PR 到next分支实现影响终端用户的新功能发 PR 到next分支实现不影响终端用户的新功能发 PR 到维护分支main。Changelog 与 Changeset仓库使用 changesets 来自动化 Biome 二进制、JavaScript 库的发布以及为每个库生成CHANGELOG.md。创建 changesetCreate a changeset如果你的 PR 是对 Biome 工具链或已发布 Biome crates 用户可见的 bugfix/feature鼓励提供changeset。不要手动创建使用命令just new-changeset该脚本底层使用pnpm因此运行前需确保已在仓库根目录执行过pnpm i从 justfile 可见它实际执行pnpm changeset。命令会通过交互式 prompt 让你选择涉及的库每个库的变更类型major/minor/patch变更描述将作为文件名。创建出的 changeset 文件位于.changeset文件夹可打开文件补充更多信息。如果要添加标题请使用####或#####级别其他级别的标题会搞乱最终的 CHANGELOG 并破坏上游工具。仓库 .changeset 目录中存在真实样例例如 .changeset/brave-deer-begin.md--- biomejs/biome: patch --- Fixed #11351: useSimplifiedLogicExpression no longer reports boolean literals on the right side of || and outside boolean contexts, ...而 .changeset/config.json 展示了 changesets 配置fixed组把biomejs/biome与所有平台 CLI 包、WASM 包绑定在一起同步发布baseBranch为main并ignore了biomejs/aria-data、tailwindcss-config-analyzer等辅助包。选择正确的包Choose the correct packages绝大多数情况下选择biomejs/biome主包即可changeset 的 frontmatter 形如--- biomejs/biome: patch --- Description here...选择正确的变更类型Choose the correct type of change团队对biomejs/biome包的major变更非常严格一般规则patch任何修复 bug 的变更minor对用户可用的新功能major破坏用户 API 的变更。选择minor或major时请确保 PR 目标是next分支而非main。编写 changesetWriting a changesetchangeset 描述应遵循的准则只写面向用户的变更。内部变更如不影响用户行为的重构不需要 changeset简洁清晰。changeset 不是文档也不是测试用例应让读者快速了解变更概览通常 13 句话更长的 changeset 意味着用户应更关注该变更新增 lint 规则用内联代码片段简单场景或代码块复杂场景展示一个 invalid 用例若确有必要也可展示 valid 用例修改既有规则清楚展示现在什么被判为 invalid 而以前不会或反之可同时展示 invalid 与 valid 两种用例格式化器变更用diff代码块展示格式化前后变化解析器变更通常一个简短的内联示例说明现在能解析什么以前不能或反之多行更清晰时用代码块描述你的工作用过去时如 Added new feature、Fixed edge case描述 Biome 行为用现在时如 Biome now supports ...修复 bug 时以 issue 链接开头如 Fixed [#4444]...引用规则时附上规则文档链接引用 assist 时附上 assist 文档链接每句话以句号.结尾。不确定时可参考既有 changesets 或CHANGELOG.md最近的条目仓库根 CHANGELOG.md 与 CHANGELOG_v1.md 记录了历次变更。文档Documentation涉及新功能或既有功能变更的 PR必须同步更新文档对规则rules、assist 及其选项文档通过内联 rustdoc注释完成即文档写在代码里其他文档更新如新的格式化选项应向官网仓库的next分支提交 PR并在功能 PR 中链接该文档 PR。版本号Versioning遵循 VS Code 扩展预发布规范奇数 minor 版本用于预发布如*.5.*偶数 minor 版本用于正式发布如*.6.*。发布流程ReleasingBeta 发布运行betaworkflow输入即将发布的版本号每次发布递增如2.0.0-beta.1如果你是 Core Contributor批准部署。仓库中对应 workflow 为 .github/workflows/beta.yml。常规发布Regular releases发布前的准备确认 milestone 下的所有 issues/PRs 已完成将规则元数据中的version: next全部替换为新版本号正常应自动化完成如需手动可使用 scripts/update-next-version.sh。发布新的minor/major版本时创建从next到main的 PR解决代码冲突并确保新功能有对应的文档 PR合并next到main推荐使用 merge commit不要用 squash merge会丢失提交历史若要发布 crates将所有 crate 的version更新为同一版本根Cargo.toml与crates/**/Cargo.tomllint 规则实现中有version元数据字段新规则的该字段为next必须更新为新版本号合并ci: releasePR 后 release workflow 开始运行产物编译完成后需要 Core Contributors 成员手动批准发布 major 版本后可更新update-preview-version.mjs脚本确保未来 preview 版本号的 patch 版本高于当前package.json清单中的值确保为主仓库与官网创建新的next分支。patch发布只需合并ci: releasePR无需触碰next分支。Crates 发布手动触发Publish cratesworkflow视情况选择 minor 或 patch它会自动打开一个 PR 更新所有可发布 crate 的版本自行审查并合并该 PR同一 workflow 会向crates.io发布 crate 并推送 tag。仓库中对应 workflow 为 .github/workflows/publish-crates.yml。资源与团队成员学习资源Resources文档推荐了多个帮助理解 Biome 项目与代码库的资源Rust Dublin 的 Biome 演讲、Rome 现代工具链演讲、如何在 Biome 中创建 lint 规则的视频等。当前成员Current Members成员按字母顺序排列分为 Lead team3 人、Core Contributors team5 人、Maintainers team10 人并列出 Past Maintainers含 Core contributor 与 Maintainer 历史成员。总结一次完整贡献的检查清单把整份贡献指南浓缩为一条可执行的路径提问/报 bug→ 先搜 Discussion/Issues确认未报告、未在 main 修复搭环境→rustup安装 stable 工具链 → 克隆仓库 →just install-tools→pnpm install写代码→ 在对应子 crate 中实现涉及规则用just new-*-lintrule脚手架遵守命名与文档规范rustdoc 内联文档跑测试→cargo t跑 crate 级测试、just test-crate name、just test-doc快照失败用cargo insta review/accept/reject构建验证→ 调试用cargo build --bin biometarget/debug/biome调试栈用--profile debugging生产构建用BIOME_VERSION... cargo build --bin biome --releasecodegen 与检查→ 按改动领域运行just gen-analyzer/just gen-bindings或全量just ready再跑just f与just l提交与 PR→ 遵循 Conventional Commits 前缀按改动性质选择main/next分支使用 AI 辅助务必在 PR 中披露且不要用 AI 写 PR 描述changeset→ 用户可见变更用just new-changeset生成按patch/minor/major选择类型并遵守书写规范跟进发布→ 遵循 branch/versioning 策略等待 release workflow 与 Core Contributors 审批。按此流程走完你的贡献就有机会被合并进 Biome 工具链并进入面向全 Web 开发者的 formatter 与 linter 之中。赞分享开发工具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点击查看免费下载相关推荐Pydantic 贡献指南从环境搭建到代码合并的完整开发工作流Pydantic 贡献指南从环境搭建到代码合并的完整开发工作流 本篇技术指南以 Pydantic 官方贡献文档仓库内 docs/contributing.m后端序列化OmniRoute 开源贡献指南从环境搭建到合并 PR 的完整开发工作流OmniRoute 开源贡献指南从环境搭建到合并 PR 的完整开发工作流 OmniRoute 是一个以 MIT 协议开源的统一 AI 网关项目通过单一 Op后端API网关LLM 网关人工智能大模型MCP 服务桌面应用External Secrets Operator 贡献指南从开发环境搭建到 PR 合并的完整工作流External Secrets Operator 贡献指南从开发环境搭建到 PR 合并的完整工作流 本篇技术指南以仓库根目录 CONTRIBUTING.md云原生运维创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
