asdf 贡献指南从 Bug 报告、核心开发到插件与文档的完整协作手册【免费下载链接】asdfExtendable version manager with support for Ruby, Node.js, Elixir, Erlang more项目地址: https://gitcode.com/GitHub_Trending/as/asdfasdf 是一款可扩展的版本管理器支持 Ruby、Node.js、Elixir、Erlang 等多种语言运行时其核心设计围绕插件体系展开。本篇技术指南以仓库根目录的 CONTRIBUTING.md 为骨架系统讲解 asdf 开源协作的完整流程如何正确区分并报告核心 Bug、如何提交新特性提案、如何搭建本地开发环境并运行 lint 与 Bats 测试、如何遵循 Conventional Commits 规范提交 Pull Request以及如何参与文档维护、第一方插件维护和插件生态建设。读完后你将掌握一套可直接落地的 asdf 协作与开发实战方案。先厘清贡献的七条通道asdf 的贡献路径在 CONTRIBUTING.md 中被明确划分为七个方向覆盖了从使用者到核心开发者的完整参与链路核心 Bug 报告发现并定位 asdf 本体的问题新特性/提案在动手实现前与核心团队讨论设计核心开发修改 asdf 本体代码详见 docs/contribute/core.md文档维护改进文档站点内容详见 docs/contribute/documentation.md第一方插件维护协助维护官方出品的插件详见 docs/contribute/first-party-plugins.md创建新插件为语言/工具编写 asdf 插件详见 docs/plugins/create.mdGitHub Actions 相关参与 asdf 官方 GitHub Actions 的维护详见 docs/contribute/github-actions.md。下面逐一深入每一通道并结合仓库源码说明其底层运作方式。报告 Bug先分清是 asdf 的问题还是插件的问题asdf 的插件体系决定了“某个工具安装/使用异常”很可能是插件层面的缺陷而非 asdf 核心的问题。因此报告 Bug 的第一步是定位责任边界。第一步判断 Bug 归属若某个 Bug 只在使用 asdf 安装的某一个工具时出现而其他工具正常那么问题大概率出在插件上。此时应找到该插件的仓库地址asdf plugin list --urls该命令会列出当前已安装的每个插件及其源码仓库 URL。随后前往对应插件仓库的 Issues 区检索是否已有相同报告若没有再在该插件仓库新建 Issue。第二步检索已有报告确认是 asdf 核心问题时先检查是否已在既有 Issues 中被报告过。CONTRIBUTING.md 明确要求报告时尽量具体——包括复现步骤、预期行为与实际行为、相关命令输出、.tool-versions内容与操作系统环境等信息越完整越容易被维护者复现和修复。第三步新特性先提案后实现对于新功能CONTRIBUTING.md 明确要求先提交 Feature Request 与核心团队讨论方案再进入实现阶段。这避免了贡献者投入大量精力实现一个与项目方向不一致的功能。asdf 的发布节奏与特性规划是强流程化的这一点在“Pull Requests、Releases 与 Conventional Commits”一节还会进一步展开。核心开发搭建本地开发环境核心开发指南的完整版本见 docs/contribute/core.md其核心链路如下。Fork 与克隆首先在 GitHub 上 Fork asdf 仓库然后克隆你的分支或直接克隆上游默认分支# 克隆你的 fork git clone https://github.com/GITHUB_USER/asdf.git # 或克隆上游 asdf git clone https://github.com/asdf-vm/asdf.git用 asdf 管理开发工具链仓库根目录的 .tool-versions 声明了 asdf 核心开发所需的全部工具版本这正是 asdf「dogfooding」自己的体现——用 asdf 来管理 asdf 的开发依赖bats 1.8.2 shellcheck 0.10.0 shfmt 3.6.0 golang 1.26.3如果你希望用 asdf 自身管理这些工具先添加对应插件asdf plugin add bats https://github.com/timgluz/asdf-bats.git asdf plugin add shellcheck https://github.com/luizm/asdf-shellcheck.git asdf plugin add shfmt https://github.com/luizm/asdf-shfmt.git然后按.tool-versions中声明的版本安装asdf install上述工具的角色分别是bats-coreBash Automated Testing System用于对 Bash 或 POSIX 兼容脚本做单元测试shellcheckShell 脚本静态分析工具shfmtShell 解析器、格式化器与解释器基于 mvdan/sh支持 Bashgolangasdf 核心 CLI 的 Go 实现仓库 go.mod、cmd、internal 目录均为 Go 代码所需的编译器。避免自锁用$ASDF_DIR在本地试运行改动由于开发 asdf 过程中你随时可能破坏 asdf 自身的功能官方建议在本地开发机上可以不用 asdf 管理这些工具。若想在不改动已安装 asdf 的前提下试用你的改动可以设置$ASDF_DIR指向克隆仓库的路径并临时把该仓库的bin与shims目录前置到PATH中export ASDF_DIR/path/to/your/asdf-repo export PATH$ASDF_DIR/bin:$ASDF_DIR/shims:$PATH这样你运行的 asdf 命令来自当前开发分支而不是系统里已安装的版本。本地质量保障格式、Lint 与测试在提交或推送之前最好先在本地完成格式化、静态检查与测试。CONTRIBUTING.md 与 docs/contribute/core.md 给出的标准命令如下# Lint仅检查发现问题即报错 ./scripts/lint.bash --check # Fix Format自动修复可修复的问题 ./scripts/lint.bash --fix # 运行全部测试 ./scripts/test.bash # 仅运行某个命令的测试 bats test/list_commands.bash注意bats test/xxx.bats与./scripts/test.bash是两套执行入口前者直接针对单个测试文件后者则携带统一选项执行test/目录下的全部测试。lint 脚本的实际执行内容阅读 scripts/lint.bash 源码可以看到--check与--fix两个模式背后实际执行了四道检查且要求必须从仓库根目录执行脚本通过git rev-parse --show-toplevel与pwd -P比对来强制这一点shfmt 风格检查对internal/completions/*.bash、scripts/*.bash、test/test_helpers.bash、test/fixtures/*/bin/*等 Bash 文件使用--language-dialect bash --indent 2对test/*.bats使用--language-dialect bats --indent 2。check 模式用--difffix 模式用--writeshellcheck 静态分析同样覆盖上述 Bash 与 Bats 文件Bash 文件使用--shell bash --external-sourcesBats 文件使用--shell bats --external-source自定义 Python 风格检查调用同目录下的 scripts/checkstyle.pyfix 模式下追加--fix参数。在 CI 中若缺少python3会直接失败本地缺少则给出警告并跳过fish 补全脚本检查对 internal/completions/asdf.fish 使用fish_indent检查/写入。仓库还预留了 elvish、nushell、powershell 的 lint 占位但目前这些语言的 linter/formatter 尚不成熟被注释掉。测试脚本的实际执行方式scripts/test.bash 是全部测试的统一入口其关键行为包括test_directory./test bats_options(--timing --print-output-on-failure) if command -v parallel /dev/null; then bats_options(--jobs 2 --no-parallelize-within-files) elif [[ -n ${CI-} ]]; then # CI 环境必须安装 GNU parallel否则直接报错退出 fi即检测到GNU parallel时以 2 个任务并行执行测试同一文件内部不并行在 CI 环境中缺失 parallel 会直接报错本地缺失则提示“安装 GNU parallel 可加速测试”。执行的是bats --timing --print-output-on-failure ./test其中--timing输出每个用例耗时、--print-output-on-failure在失败时打印相关输出便于定位。测试用例本身集中在 test/ 目录覆盖asdf_sh.bats、install_command.bats、plugin_add_command.bats、shim_exec.bats、set_command.bats等数十个命令级测试文件以及 test/test_helpers.bash 提供的公共断言工具还有test/fixtures/dummy_plugin/、dummy_broken_plugin/、dummy_legacy_plugin/等模拟插件夹具。Gitignore 约定仓库的 .gitignore 仅忽略项目特定产物如/installs、/downloads、/shims、repository、dist/以及编译出的asdf二进制等/installs /downloads /shims repository .vagrant keyrings /tmp dist/ # ignore build binary asdfCONTRIBUTING.md 强调与你的操作系统、个人工具或工作流相关的文件应加入你的全局.gitignore而不是提交进 asdf 仓库。用.git-blame-ignore-revs降低 blame 噪音asdf 使用 .git-blame-ignore-revs 文件来减少大规模格式化提交对git blame的干扰。手动使用时通过--ignore-revs-file指定git blame --ignore-revs-file .git-blame-ignore-revs ./test/install_command.bats也可以配置为每次 blame 自动生效git config blame.ignoreRevsFile .git-blame-ignore-revs若使用 VSCode GitLens可写入.vscode/settings.json{ gitlens.advanced.blame.customArguments: [ --ignore-revs-file, .git-blame-ignore-revs ] }Bats 测试必须覆盖新代码路径CONTRIBUTING.md 对测试有硬性要求新功能必须附带测试Bug 修复的评审也会因测试而加速。写测试之前务必先阅读test/目录下已有的测试文件bats-core 官方文档scripts/test.bash 中使用的 Bats 选项--timing、--print-output-on-failure、--jobs 2等。Bats 调试技巧TAP 输出与3Bats 调试有时比较困难。使用-t标志启用 TAP 输出后即可借助特殊文件描述符3在测试执行过程中打印内容例如# test/some_tests.bats printf %s\n Will not be printed during bats test/some_tests.bats printf %s\n Will be printed during bats -t test/some_tests.bats 3不带-t运行时普通printf输出被吞掉带上-t后3的内容会实时显示极大方便了用例调试。这也是 bats-core「Printing to the Terminal」机制的典型用法。Pull Request、发布与 Conventional Commitsasdf 采用名为Release Please的自动化发布工具通过读取自上次发布以来的提交历史自动按SemVer规则升级版本号并生成 CHANGELOG.md。仓库根目录的 release-please-config.json 与 .release-please-manifest.json 就是这一流程的配置文件。提交信息规范PR 标题将直接成为默认分支上的提交信息格式因此PR 标题必须遵循 Conventional Commits 格式由 GitHub Action 强制校验type[optional scope][optional !]: description !-- examples -- fix: some fix feat: a new feature docs: some documentation update docs(website): some change for the website feat!: feature with breaking change完整的type列表为feat、fix、docs、style、refactor、perf、test、build、ci、chore、revert。类型与版本号的对应关系!表示破坏性变更fix产生新的 SemVerpatch版本feat产生新的 SemVerminor版本type!产生新的 SemVermajor版本。例如feat!: rewrite shim resolution这样的标题会触发主版本号升级。这一机制保证了 CHANGELOG 与版本语义的一致性也让维护者无需手动管理版本号。文档贡献VitePress 站点与多语言维护文档与站点贡献的完整指南见 docs/contribute/documentation.md。asdf 文档站基于VitePress v2构建此前经历过 Docsify、VuePress 的迁移选择 VitePress 的原因之一是支持无 JavaScript 时的纯 HTML 回退。搭建文档开发环境文档站的工具链由 docs/.tool-versions 通过 asdf 管理Node.js插件添加方式asdf plugin add nodejs https://github.com/asdf-vm/asdf-nodejs asdf install随后安装 Node.js 依赖并启动本地开发服务器npm install npm run dev提交前先格式化代码npm run fmt站点配置集中在三个文件中根配置 docs/.vitepress/config.js 定义站点根配置与多语言locales导航栏与侧边栏的大对象被按语言抽取到 docs/.vitepress/navbars.js 与 docs/.vitepress/sidebars.js。多语言i18n组织方式VitePress 对国际化有一等支持docs/.vitepress/config.js中的locales键定义了各语言及其导航/侧边栏引用当前仓库内置了英文root、巴西葡萄牙语pt-br、简体中文zh-hans等多个语言版本。每种语言的 Markdown 内容必须放在与locales键同名的目录下docs ├─ README.md ├─ foo.md ├─ nested │ └─ README.md └─ pt-BR ├─ README.md ├─ foo.md └─ nested └─ README.md新增语言时需要同步补齐该语言目录下的整套 Markdown 文件并在locales中注册对应的label、lang与导航/侧边栏配置。例如新增“简体中文”就需要让docs/zh-hans/下的文件与英文版一一对应仓库中 docs/zh-hans/、docs/ja-jp/、docs/ko-kr/、docs/pt-br/ 即是这一规则的实例。文档类 PR 的标题需使用 Conventional Commit 的docs类型格式为docs: description发布流程与核心贡献一致详见 docs/contribute/core.md。第一方插件与插件生态维护第一方插件asdf 核心团队日常工作中使用并维护着若干官方插件具体清单见 docs/contribute/first-party-plugins.md包括Elixirasdf-elixirErlangasdf-erlangNode.jsasdf-nodejsRubyasdf-ruby这些插件的维护和文档贡献随时欢迎外部帮助贡献方式与各插件仓库的 Issues、对话和贡献指南保持一致。参与社区插件生态对于社区插件官方文档指向了三个入口asdf-community组织社区驱动的协作项目负责 asdf 插件的长期维护asdf-plugins短名仓库asdf 核心用于查找热门插件的短名列表GitHub 的asdf-plugin主题搜索发现更多社区插件。创建你自己的插件为你的语言或工具编写插件请完整阅读 docs/plugins/create.md。插件是 asdf 可扩展性的基石——任何语言都可以通过插件获得版本管理能力这也正是「用一个 CLI 管理所有语言运行时」这一设计目标的实现方式。GitHub Actions 相关贡献asdf 官方维护着一套独立的 GitHub Actions 仓库asdf actions用于在 CI 中安装 asdf 并解析.tool-versions。相关的既有 Issues、讨论与贡献指南都在该仓库中进行见 docs/contribute/github-actions.md。值得注意的是asdf 自己的 CI 同样依赖这一体系仓库中的 scripts/install_dependencies.bash 展示了在 GitHub Actions 中如何为不同 Runner 安装测试依赖——Linux 上通过 apt 与二进制下载安装fish、powershell、elvish、nushell、parallel等并校验GITHUB_ACTIONS与RUNNER_OS环境变量macOS 上则统一走brew install最后按 .tool-versions 中声明的 bats 版本克隆bats-core并加入$GITHUB_PATH。这说明 asdf 的整个测试矩阵就是按照贡献指南中的流程在真实 CI 中自动运行的贡献者在本地的验证步骤与 CI 完全同源。结语从 CONTRIBUTING.md 出发asdf 的协作体系可以总结为一条清晰的主线先定位问题归属核心还是插件再按通道参与——报告 Bug 要具体、新特性要先提案、核心改动必须配套 lint 与 Bats 测试、PR 标题遵循 Conventional Commits 以驱动 Release Please 自动发布、文档与插件生态则各有其独立贡献路径。这份手册既是新贡献者的入门地图也是老贡献者保持提交规范一致性的依据。无论你从哪个入口切入asdf 都期待你的参与。【免费下载链接】asdfExtendable version manager with support for Ruby, Node.js, Elixir, Erlang more项目地址: https://gitcode.com/GitHub_Trending/as/asdf创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 
长河君 · 2026/9/11 17:51:26 · 阅读 1.2k asdf 贡献指南：从 Bug 报告、核心开发到插件与文档的完整协作手册
asdf 贡献指南从 Bug 报告、核心开发到插件与文档的完整协作手册【免费下载链接】asdfExtendable version manager with support for Ruby, Node.js, Elixir, Erlang more项目地址: https://gitcode.com/GitHub_Trending/as/asdfasdf 是一款可扩展的版本管理器支持 Ruby、Node.js、Elixir、Erlang 等多种语言运行时其核心设计围绕插件体系展开。本篇技术指南以仓库根目录的 CONTRIBUTING.md 为骨架系统讲解 asdf 开源协作的完整流程如何正确区分并报告核心 Bug、如何提交新特性提案、如何搭建本地开发环境并运行 lint 与 Bats 测试、如何遵循 Conventional Commits 规范提交 Pull Request以及如何参与文档维护、第一方插件维护和插件生态建设。读完后你将掌握一套可直接落地的 asdf 协作与开发实战方案。先厘清贡献的七条通道asdf 的贡献路径在 CONTRIBUTING.md 中被明确划分为七个方向覆盖了从使用者到核心开发者的完整参与链路核心 Bug 报告发现并定位 asdf 本体的问题新特性/提案在动手实现前与核心团队讨论设计核心开发修改 asdf 本体代码详见 docs/contribute/core.md文档维护改进文档站点内容详见 docs/contribute/documentation.md第一方插件维护协助维护官方出品的插件详见 docs/contribute/first-party-plugins.md创建新插件为语言/工具编写 asdf 插件详见 docs/plugins/create.mdGitHub Actions 相关参与 asdf 官方 GitHub Actions 的维护详见 docs/contribute/github-actions.md。下面逐一深入每一通道并结合仓库源码说明其底层运作方式。报告 Bug先分清是 asdf 的问题还是插件的问题asdf 的插件体系决定了“某个工具安装/使用异常”很可能是插件层面的缺陷而非 asdf 核心的问题。因此报告 Bug 的第一步是定位责任边界。第一步判断 Bug 归属若某个 Bug 只在使用 asdf 安装的某一个工具时出现而其他工具正常那么问题大概率出在插件上。此时应找到该插件的仓库地址asdf plugin list --urls该命令会列出当前已安装的每个插件及其源码仓库 URL。随后前往对应插件仓库的 Issues 区检索是否已有相同报告若没有再在该插件仓库新建 Issue。第二步检索已有报告确认是 asdf 核心问题时先检查是否已在既有 Issues 中被报告过。CONTRIBUTING.md 明确要求报告时尽量具体——包括复现步骤、预期行为与实际行为、相关命令输出、.tool-versions内容与操作系统环境等信息越完整越容易被维护者复现和修复。第三步新特性先提案后实现对于新功能CONTRIBUTING.md 明确要求先提交 Feature Request 与核心团队讨论方案再进入实现阶段。这避免了贡献者投入大量精力实现一个与项目方向不一致的功能。asdf 的发布节奏与特性规划是强流程化的这一点在“Pull Requests、Releases 与 Conventional Commits”一节还会进一步展开。核心开发搭建本地开发环境核心开发指南的完整版本见 docs/contribute/core.md其核心链路如下。Fork 与克隆首先在 GitHub 上 Fork asdf 仓库然后克隆你的分支或直接克隆上游默认分支# 克隆你的 fork git clone https://github.com/GITHUB_USER/asdf.git # 或克隆上游 asdf git clone https://github.com/asdf-vm/asdf.git用 asdf 管理开发工具链仓库根目录的 .tool-versions 声明了 asdf 核心开发所需的全部工具版本这正是 asdf「dogfooding」自己的体现——用 asdf 来管理 asdf 的开发依赖bats 1.8.2 shellcheck 0.10.0 shfmt 3.6.0 golang 1.26.3如果你希望用 asdf 自身管理这些工具先添加对应插件asdf plugin add bats https://github.com/timgluz/asdf-bats.git asdf plugin add shellcheck https://github.com/luizm/asdf-shellcheck.git asdf plugin add shfmt https://github.com/luizm/asdf-shfmt.git然后按.tool-versions中声明的版本安装asdf install上述工具的角色分别是bats-coreBash Automated Testing System用于对 Bash 或 POSIX 兼容脚本做单元测试shellcheckShell 脚本静态分析工具shfmtShell 解析器、格式化器与解释器基于 mvdan/sh支持 Bashgolangasdf 核心 CLI 的 Go 实现仓库 go.mod、cmd、internal 目录均为 Go 代码所需的编译器。避免自锁用$ASDF_DIR在本地试运行改动由于开发 asdf 过程中你随时可能破坏 asdf 自身的功能官方建议在本地开发机上可以不用 asdf 管理这些工具。若想在不改动已安装 asdf 的前提下试用你的改动可以设置$ASDF_DIR指向克隆仓库的路径并临时把该仓库的bin与shims目录前置到PATH中export ASDF_DIR/path/to/your/asdf-repo export PATH$ASDF_DIR/bin:$ASDF_DIR/shims:$PATH这样你运行的 asdf 命令来自当前开发分支而不是系统里已安装的版本。本地质量保障格式、Lint 与测试在提交或推送之前最好先在本地完成格式化、静态检查与测试。CONTRIBUTING.md 与 docs/contribute/core.md 给出的标准命令如下# Lint仅检查发现问题即报错 ./scripts/lint.bash --check # Fix Format自动修复可修复的问题 ./scripts/lint.bash --fix # 运行全部测试 ./scripts/test.bash # 仅运行某个命令的测试 bats test/list_commands.bash注意bats test/xxx.bats与./scripts/test.bash是两套执行入口前者直接针对单个测试文件后者则携带统一选项执行test/目录下的全部测试。lint 脚本的实际执行内容阅读 scripts/lint.bash 源码可以看到--check与--fix两个模式背后实际执行了四道检查且要求必须从仓库根目录执行脚本通过git rev-parse --show-toplevel与pwd -P比对来强制这一点shfmt 风格检查对internal/completions/*.bash、scripts/*.bash、test/test_helpers.bash、test/fixtures/*/bin/*等 Bash 文件使用--language-dialect bash --indent 2对test/*.bats使用--language-dialect bats --indent 2。check 模式用--difffix 模式用--writeshellcheck 静态分析同样覆盖上述 Bash 与 Bats 文件Bash 文件使用--shell bash --external-sourcesBats 文件使用--shell bats --external-source自定义 Python 风格检查调用同目录下的 scripts/checkstyle.pyfix 模式下追加--fix参数。在 CI 中若缺少python3会直接失败本地缺少则给出警告并跳过fish 补全脚本检查对 internal/completions/asdf.fish 使用fish_indent检查/写入。仓库还预留了 elvish、nushell、powershell 的 lint 占位但目前这些语言的 linter/formatter 尚不成熟被注释掉。测试脚本的实际执行方式scripts/test.bash 是全部测试的统一入口其关键行为包括test_directory./test bats_options(--timing --print-output-on-failure) if command -v parallel /dev/null; then bats_options(--jobs 2 --no-parallelize-within-files) elif [[ -n ${CI-} ]]; then # CI 环境必须安装 GNU parallel否则直接报错退出 fi即检测到GNU parallel时以 2 个任务并行执行测试同一文件内部不并行在 CI 环境中缺失 parallel 会直接报错本地缺失则提示“安装 GNU parallel 可加速测试”。执行的是bats --timing --print-output-on-failure ./test其中--timing输出每个用例耗时、--print-output-on-failure在失败时打印相关输出便于定位。测试用例本身集中在 test/ 目录覆盖asdf_sh.bats、install_command.bats、plugin_add_command.bats、shim_exec.bats、set_command.bats等数十个命令级测试文件以及 test/test_helpers.bash 提供的公共断言工具还有test/fixtures/dummy_plugin/、dummy_broken_plugin/、dummy_legacy_plugin/等模拟插件夹具。Gitignore 约定仓库的 .gitignore 仅忽略项目特定产物如/installs、/downloads、/shims、repository、dist/以及编译出的asdf二进制等/installs /downloads /shims repository .vagrant keyrings /tmp dist/ # ignore build binary asdfCONTRIBUTING.md 强调与你的操作系统、个人工具或工作流相关的文件应加入你的全局.gitignore而不是提交进 asdf 仓库。用.git-blame-ignore-revs降低 blame 噪音asdf 使用 .git-blame-ignore-revs 文件来减少大规模格式化提交对git blame的干扰。手动使用时通过--ignore-revs-file指定git blame --ignore-revs-file .git-blame-ignore-revs ./test/install_command.bats也可以配置为每次 blame 自动生效git config blame.ignoreRevsFile .git-blame-ignore-revs若使用 VSCode GitLens可写入.vscode/settings.json{ gitlens.advanced.blame.customArguments: [ --ignore-revs-file, .git-blame-ignore-revs ] }Bats 测试必须覆盖新代码路径CONTRIBUTING.md 对测试有硬性要求新功能必须附带测试Bug 修复的评审也会因测试而加速。写测试之前务必先阅读test/目录下已有的测试文件bats-core 官方文档scripts/test.bash 中使用的 Bats 选项--timing、--print-output-on-failure、--jobs 2等。Bats 调试技巧TAP 输出与3Bats 调试有时比较困难。使用-t标志启用 TAP 输出后即可借助特殊文件描述符3在测试执行过程中打印内容例如# test/some_tests.bats printf %s\n Will not be printed during bats test/some_tests.bats printf %s\n Will be printed during bats -t test/some_tests.bats 3不带-t运行时普通printf输出被吞掉带上-t后3的内容会实时显示极大方便了用例调试。这也是 bats-core「Printing to the Terminal」机制的典型用法。Pull Request、发布与 Conventional Commitsasdf 采用名为Release Please的自动化发布工具通过读取自上次发布以来的提交历史自动按SemVer规则升级版本号并生成 CHANGELOG.md。仓库根目录的 release-please-config.json 与 .release-please-manifest.json 就是这一流程的配置文件。提交信息规范PR 标题将直接成为默认分支上的提交信息格式因此PR 标题必须遵循 Conventional Commits 格式由 GitHub Action 强制校验type[optional scope][optional !]: description !-- examples -- fix: some fix feat: a new feature docs: some documentation update docs(website): some change for the website feat!: feature with breaking change完整的type列表为feat、fix、docs、style、refactor、perf、test、build、ci、chore、revert。类型与版本号的对应关系!表示破坏性变更fix产生新的 SemVerpatch版本feat产生新的 SemVerminor版本type!产生新的 SemVermajor版本。例如feat!: rewrite shim resolution这样的标题会触发主版本号升级。这一机制保证了 CHANGELOG 与版本语义的一致性也让维护者无需手动管理版本号。文档贡献VitePress 站点与多语言维护文档与站点贡献的完整指南见 docs/contribute/documentation.md。asdf 文档站基于VitePress v2构建此前经历过 Docsify、VuePress 的迁移选择 VitePress 的原因之一是支持无 JavaScript 时的纯 HTML 回退。搭建文档开发环境文档站的工具链由 docs/.tool-versions 通过 asdf 管理Node.js插件添加方式asdf plugin add nodejs https://github.com/asdf-vm/asdf-nodejs asdf install随后安装 Node.js 依赖并启动本地开发服务器npm install npm run dev提交前先格式化代码npm run fmt站点配置集中在三个文件中根配置 docs/.vitepress/config.js 定义站点根配置与多语言locales导航栏与侧边栏的大对象被按语言抽取到 docs/.vitepress/navbars.js 与 docs/.vitepress/sidebars.js。多语言i18n组织方式VitePress 对国际化有一等支持docs/.vitepress/config.js中的locales键定义了各语言及其导航/侧边栏引用当前仓库内置了英文root、巴西葡萄牙语pt-br、简体中文zh-hans等多个语言版本。每种语言的 Markdown 内容必须放在与locales键同名的目录下docs ├─ README.md ├─ foo.md ├─ nested │ └─ README.md └─ pt-BR ├─ README.md ├─ foo.md └─ nested └─ README.md新增语言时需要同步补齐该语言目录下的整套 Markdown 文件并在locales中注册对应的label、lang与导航/侧边栏配置。例如新增“简体中文”就需要让docs/zh-hans/下的文件与英文版一一对应仓库中 docs/zh-hans/、docs/ja-jp/、docs/ko-kr/、docs/pt-br/ 即是这一规则的实例。文档类 PR 的标题需使用 Conventional Commit 的docs类型格式为docs: description发布流程与核心贡献一致详见 docs/contribute/core.md。第一方插件与插件生态维护第一方插件asdf 核心团队日常工作中使用并维护着若干官方插件具体清单见 docs/contribute/first-party-plugins.md包括Elixirasdf-elixirErlangasdf-erlangNode.jsasdf-nodejsRubyasdf-ruby这些插件的维护和文档贡献随时欢迎外部帮助贡献方式与各插件仓库的 Issues、对话和贡献指南保持一致。参与社区插件生态对于社区插件官方文档指向了三个入口asdf-community组织社区驱动的协作项目负责 asdf 插件的长期维护asdf-plugins短名仓库asdf 核心用于查找热门插件的短名列表GitHub 的asdf-plugin主题搜索发现更多社区插件。创建你自己的插件为你的语言或工具编写插件请完整阅读 docs/plugins/create.md。插件是 asdf 可扩展性的基石——任何语言都可以通过插件获得版本管理能力这也正是「用一个 CLI 管理所有语言运行时」这一设计目标的实现方式。GitHub Actions 相关贡献asdf 官方维护着一套独立的 GitHub Actions 仓库asdf actions用于在 CI 中安装 asdf 并解析.tool-versions。相关的既有 Issues、讨论与贡献指南都在该仓库中进行见 docs/contribute/github-actions.md。值得注意的是asdf 自己的 CI 同样依赖这一体系仓库中的 scripts/install_dependencies.bash 展示了在 GitHub Actions 中如何为不同 Runner 安装测试依赖——Linux 上通过 apt 与二进制下载安装fish、powershell、elvish、nushell、parallel等并校验GITHUB_ACTIONS与RUNNER_OS环境变量macOS 上则统一走brew install最后按 .tool-versions 中声明的 bats 版本克隆bats-core并加入$GITHUB_PATH。这说明 asdf 的整个测试矩阵就是按照贡献指南中的流程在真实 CI 中自动运行的贡献者在本地的验证步骤与 CI 完全同源。结语从 CONTRIBUTING.md 出发asdf 的协作体系可以总结为一条清晰的主线先定位问题归属核心还是插件再按通道参与——报告 Bug 要具体、新特性要先提案、核心改动必须配套 lint 与 Bats 测试、PR 标题遵循 Conventional Commits 以驱动 Release Please 自动发布、文档与插件生态则各有其独立贡献路径。这份手册既是新贡献者的入门地图也是老贡献者保持提交规范一致性的依据。无论你从哪个入口切入asdf 都期待你的参与。【免费下载链接】asdfExtendable version manager with support for Ruby, Node.js, Elixir, Erlang more项目地址: https://gitcode.com/GitHub_Trending/as/asdf创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考