asdf 核心开发贡献指南从环境搭建、Bats 测试到 Conventional Commits 发布全流程【免费下载链接】asdfExtendable version manager with support for Ruby, Node.js, Elixir, Erlang more项目地址: https://gitcode.com/GitHub_Trending/as/asdfasdf是一个可扩展的版本管理器通过插件机制统一管理 Ruby、Node.js、Elixir、Erlang 等多种语言运行时见 README.md。本文以官方核心贡献指南 docs/contribute/core.md 为骨架结合仓库内的脚本、工作流与测试源码完整讲解 asdf 核心开发的参与流程如何用 asdf 自身搭建开发环境、通过$ASDF_DIR在隔离环境中试运行改动、执行 lint/format/test 质量门槛、编写 Bats 测试以及如何用 Conventional Commits 驱动 Release Please 自动化发布。读完本文你将具备向 asdf 核心仓库提交高质量 Pull Request 的完整实战能力。核心开发前的准备Fork 与克隆参与 asdf 核心开发的第一步是获取代码。官方推荐两种方式先在 GitHub 上 Fork 仓库再克隆自己的分支或者直接克隆上游仓库的默认分支# 克隆你自己的 fork git clone https://github.com/GITHUB_USER/asdf.git # 或直接克隆 asdf 上游仓库 git clone https://github.com/asdf-vm/asdf.git克隆完成后仓库根目录下的 .tool-versions 明确记录了核心开发所需的工具链版本这正是 用 asdf 开发 asdf 的体现。当前仓库中该文件内容为bats 1.8.2 shellcheck 0.10.0 shfmt 3.6.0 golang 1.26.3其中前三者是在核心开发与测试中实际使用的关键工具详见下节golang则对应仓库中的 Go 实现部分——asdf 的 CLI、completions、config、git 等模块均以 Go 编写见 cmd/ 与 internal/ 目录。如果你希望用 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然后一条命令安装全部指定版本asdf installasdf install会读取当前目录的.tool-versions文件为其中列出的每个工具安装对应版本这正是 asdf 按项目隔离工具版本的核心用法。实用建议官方文档特别提醒本地开发时可以不依赖 asdf 来管理这些工具。因为你可能在开发过程中破坏 asdf 的部分功能一旦如此依赖 asdf 的 dev tooling 也会跟着无法工作。若选择手动安装需要准备的三件套是bats-coreBash Automated Testing System用于对 Bash 或 POSIX 兼容脚本做单元测试shellcheckshell 脚本静态分析工具shfmt一个支持 bash 的 shell 解析器、格式化器与解释器自带shfmt命令。用 $ASDF_DIR 在隔离环境中试运行改动当你改了代码、又不想影响已经安装到系统里的 asdf 时官方提供了一种轻量隔离方案将$ASDF_DIR环境变量指向克隆的仓库目录并把该目录下的bin与shims目录临时加入PATH。export ASDF_DIR/path/to/your/asdf-clone export PATH$ASDF_DIR/bin:$ASDF_DIR/shims:$PATH从源码结构看test/test_helpers.bash 中的setup_asdf_dir函数正是这种隔离思想的自动化版本它把ASDF_DIR设置为$HOME/.asdf创建plugins、installs、shims、tmp子目录并将$ASDF_BIN与 shims 目录前置到PATH从而让每个测试用例都在独立的临时环境中运行、互不污染。理解了这一点你就明白为什么文档建议用$ASDF_DIR做本地试运行——它复刻了测试环境的隔离策略。质量门槛lint、format 与 test官方要求在提交或推送到远端之前最好先在本地完成格式化、lint 与测试。仓库根目录下提供了统一的脚本入口# 仅检查发现问题即报错 ./scripts/lint.bash --check # 自动修复并格式化 ./scripts/lint.bash --fix # 运行全部测试 ./scripts/test.bash # 只跑某个特定命令的测试 bats test/set_command.batslint.bash 到底检查了什么查看 scripts/lint.bash 源码可以发现--check/--fix两个模式分别映射到各工具的模式开关实际执行了四道检查shfmt 格式化检查以 2 空格缩进、bash 方言检查scripts/*.bash、test/test_helpers.bash以及test/fixtures/dummy_*_plugin/bin/*等文件同时以 bats 方言检查test/*.batsShellCheck 静态分析分别以--shell bash和--shell bats均带--external-sources检查上述同组文件自定义 Python 检查调用 scripts/checkstyle.py该脚本实现了 shellcheck 覆盖不到的团队专属规则例如禁止function fn()写法保持fn() { ... }一致风格、用$PWD替代$(pwd)避免子 shell 开销、用/dev/null替代/dev/null 21、以及禁止[ a b ]中的双等号等。它支持--fix自动修复、--internal-test-regex自检正则并在无 Python3 的本地环境自动跳过fish_indent 检查对internal/completions/asdf.fish做格式化校验对应 fish shell 的补全脚本。脚本开头还会校验当前目录必须是仓库根目录通过git rev-parse --show-toplevel对比否则直接报错退出且必须传入-c/-f/-h之一。目前 elvish、nushell、powershell 的 linter 尚未接入源码中以 TODO 注释保留。test.bash 如何跑全部测试scripts/test.bash 同样强制在仓库根目录执行然后调用 Bats 运行./test目录默认附加--timing --print-output-on-failure两个选项。值得注意的性能优化是如果检测到parallelGNU parallel命令会追加--jobs 2 --no-parallelize-within-files并行执行测试文件以加速若在 CI 环境设置了CI环境变量却没有 parallel则直接报错退出。关于示例命令的小修正core 指南中的示例命令bats test/list_commands.bash在当前的 test/ 目录中并不存在对应的list_commands.bats文件当前测试文件按*_command.bats命名如 test/set_command.bats、test/install_command.bats。实际跑单个测试文件时请按现有文件名执行例如bats test/set_command.bats。这正是以当前仓库实际内容为准的体现。Bats 测试asdf 的测试体系执行与阅读测试本地执行全部测试./scripts/test.bash官方在动手写测试前强烈建议先读三样东西test/目录下已有的测试、bats-core 官方文档以及scripts/test.bash中已有的 Bats 配置。这套测试体系覆盖了 asdf 的所有核心命令从 test/ 目录可以看到install_command.bats、set_command.bats、plugin_add_command.bats、shim_exec.bats、where_command.bats、which_command.bats等一整套按命令组织的测试文件。以 test/set_command.bats 为例可以直观看到 Bats 测试的组织方式setup()中通过test_helpers.bash提供的setup_asdf_dir、install_dummy_plugin、install_dummy_version构建隔离环境teardown()中清理每个test块用run asdf set ...执行命令并断言$status退出码与$output输出例如test set should create .tool-versions file in current directory { run asdf set dummy 1.0.0 [ $status -eq 0 ] [ -f $PROJECT_DIR/.tool-versions ] run cat $PROJECT_DIR/.tool-versions [ $output dummy 1.0.0 ] }test/test_helpers.bash 是这套测试的核心支撑库提供setup_asdf_dir、install_mock_plugin、install_mock_plugin_no_download、install_mock_legacy_plugin、install_mock_broken_plugin等工具函数配合test/fixtures/下的dummy_plugin、dummy_legacy_plugin、dummy_broken_plugin等假插件夹具实现对真实场景的模拟。调试技巧用 TAP 输出打印信息Bats 调试有时相当困难。官方给出的技巧是使用-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普通输出在测试运行时默认被吞掉只有重定向到3的内容才会在bats -t模式下显示到终端。这一行为在 bats-core 的 Printing to the Terminal 一节中有更详细的说明。测试是必需的core 指南中的提示框非常明确新功能必须配测试bug 修复也应通过测试来加速评审。请在创建 Pull Request 之前覆盖新的代码路径。CI 工作流 .github/workflows/tests.yml 也印证了这一点它通过dorny/paths-filter按改动路径文档、CLI、Go 代码分流在 Ubuntu 与 macOS 双平台矩阵上先执行scripts/install_dependencies.bash该脚本会从.tool-versions读取 bats 版本并克隆安装 bats-core同时为 Linux/macOS 安装 elvish、nushell、fish、powershell、parallel 等跨 shell 测试依赖再运行 Go 测试。这意味着你的每个改动都会在多个 shell 与平台上被验证。仓库规范.gitignore 与 .git-blame-ignore-revs.gitignore 的分工仓库根目录的 .gitignore 只忽略项目专属文件当前内容如下/installs /downloads /shims repository .vagrant keyrings /tmp dist/ # ignore build binary asdf可见它覆盖的是 asdf 运行时产生的目录installs、downloads、shims、dist/构建产物以及编译出的asdf二进制。而操作系统、编辑器或工具链特有的文件如编辑器临时文件官方建议放到你的全局.gitignore中避免把个人工作流噪音混入项目提交。.git-blame-ignore-revs让 git blame 更干净asdf使用 .git-blame-ignore-revs 来降低git blame时的噪音——像 Run shfmt on bash files、Remove inside [ 这类纯格式化或机械重构的提交会被忽略让 blame 直接定位到真正改动逻辑的那次提交。使用时手动指定git blame --ignore-revs-file .git-blame-ignore-revs ./test/install_command.bats也可以配置 git 全局启用免去每次手动指定git config blame.ignoreRevsFile .git-blame-ignore-revsIDE 同样可以接入。以 VSCode 配合 GitLens 为例在.vscode/settings.json中写入{ gitlens.advanced.blame.customArguments: [ --ignore-revs-file, .git-blame-ignore-revs ] }Pull Request 与发布Conventional Commits 驱动 Release Please自动化发布机制asdf使用 Google 的 Release Please 生成所有信息都来自自上次发布以来的提交历史。仓库中的 release-please-config.json 证实了这一机制发布类型为gofeat对应 Features、fix对应 Patches、docs对应 Documentation 章节并额外维护 SECURITY.md、各语言版 docs/guide/getting-started.md 及 cmd/asdf/main.go 等文件中的版本占位符。而 Pull Request 标题必须遵循 Conventional Commits。发布流程则由 .github/workflows/release.yml 驱动。提交信息格式Conventional Commits 的标准格式为type[optional scope][optional !]: description !-- 示例 -- 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。各类型对版本号的影响规则如下标记含义触发的版本变更!破坏性变更标记配合 type 使用fix修复 bug新的 SemVerpatchfeat新功能新的 SemVerminortype!破坏性变更新的 SemVermajorPull Request 标题必须严格遵守该格式。文档类改动如修改本文所属的 docs 站点也遵循同样的约定见 docs/contribute/documentation.md文档 PR 的标题应使用docs类型即docs: description。延伸Docker 镜像asdf社区还维护着 asdf-alpine 与 asdf-ubuntu 两个项目提供预装了部分 asdf 工具的 Docker 镜像。你可以把它们作为开发服务器的基底镜像或直接用于运行生产应用——这为在容器化环境里使用 asdf 管理运行时版本提供了现成方案。小结参与 asdf 核心开发的完整链路是Fork 克隆 → 用.tool-versionsasdf install准备工具链 → 通过$ASDF_DIR隔离试运行 → 本地跑./scripts/lint.bash与./scripts/test.bash通过质量门槛 → 编写覆盖新代码路径的 Bats 测试 → 按 Conventional Commits 规范书写 PR 标题 → 由 CI 与 Release Please 自动完成校验、测试、版本发布与变更日志生成。希望本文能帮助你顺利成为 asdf 的贡献者。【免费下载链接】asdfExtendable version manager with support for Ruby, Node.js, Elixir, Erlang more项目地址: https://gitcode.com/GitHub_Trending/as/asdf创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
asdf 核心开发贡献指南：从环境搭建、Bats 测试到 Conventional Commits 发布全流程
asdf 核心开发贡献指南从环境搭建、Bats 测试到 Conventional Commits 发布全流程【免费下载链接】asdfExtendable version manager with support for Ruby, Node.js, Elixir, Erlang more项目地址: https://gitcode.com/GitHub_Trending/as/asdfasdf是一个可扩展的版本管理器通过插件机制统一管理 Ruby、Node.js、Elixir、Erlang 等多种语言运行时见 README.md。本文以官方核心贡献指南 docs/contribute/core.md 为骨架结合仓库内的脚本、工作流与测试源码完整讲解 asdf 核心开发的参与流程如何用 asdf 自身搭建开发环境、通过$ASDF_DIR在隔离环境中试运行改动、执行 lint/format/test 质量门槛、编写 Bats 测试以及如何用 Conventional Commits 驱动 Release Please 自动化发布。读完本文你将具备向 asdf 核心仓库提交高质量 Pull Request 的完整实战能力。核心开发前的准备Fork 与克隆参与 asdf 核心开发的第一步是获取代码。官方推荐两种方式先在 GitHub 上 Fork 仓库再克隆自己的分支或者直接克隆上游仓库的默认分支# 克隆你自己的 fork git clone https://github.com/GITHUB_USER/asdf.git # 或直接克隆 asdf 上游仓库 git clone https://github.com/asdf-vm/asdf.git克隆完成后仓库根目录下的 .tool-versions 明确记录了核心开发所需的工具链版本这正是 用 asdf 开发 asdf 的体现。当前仓库中该文件内容为bats 1.8.2 shellcheck 0.10.0 shfmt 3.6.0 golang 1.26.3其中前三者是在核心开发与测试中实际使用的关键工具详见下节golang则对应仓库中的 Go 实现部分——asdf 的 CLI、completions、config、git 等模块均以 Go 编写见 cmd/ 与 internal/ 目录。如果你希望用 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然后一条命令安装全部指定版本asdf installasdf install会读取当前目录的.tool-versions文件为其中列出的每个工具安装对应版本这正是 asdf 按项目隔离工具版本的核心用法。实用建议官方文档特别提醒本地开发时可以不依赖 asdf 来管理这些工具。因为你可能在开发过程中破坏 asdf 的部分功能一旦如此依赖 asdf 的 dev tooling 也会跟着无法工作。若选择手动安装需要准备的三件套是bats-coreBash Automated Testing System用于对 Bash 或 POSIX 兼容脚本做单元测试shellcheckshell 脚本静态分析工具shfmt一个支持 bash 的 shell 解析器、格式化器与解释器自带shfmt命令。用 $ASDF_DIR 在隔离环境中试运行改动当你改了代码、又不想影响已经安装到系统里的 asdf 时官方提供了一种轻量隔离方案将$ASDF_DIR环境变量指向克隆的仓库目录并把该目录下的bin与shims目录临时加入PATH。export ASDF_DIR/path/to/your/asdf-clone export PATH$ASDF_DIR/bin:$ASDF_DIR/shims:$PATH从源码结构看test/test_helpers.bash 中的setup_asdf_dir函数正是这种隔离思想的自动化版本它把ASDF_DIR设置为$HOME/.asdf创建plugins、installs、shims、tmp子目录并将$ASDF_BIN与 shims 目录前置到PATH从而让每个测试用例都在独立的临时环境中运行、互不污染。理解了这一点你就明白为什么文档建议用$ASDF_DIR做本地试运行——它复刻了测试环境的隔离策略。质量门槛lint、format 与 test官方要求在提交或推送到远端之前最好先在本地完成格式化、lint 与测试。仓库根目录下提供了统一的脚本入口# 仅检查发现问题即报错 ./scripts/lint.bash --check # 自动修复并格式化 ./scripts/lint.bash --fix # 运行全部测试 ./scripts/test.bash # 只跑某个特定命令的测试 bats test/set_command.batslint.bash 到底检查了什么查看 scripts/lint.bash 源码可以发现--check/--fix两个模式分别映射到各工具的模式开关实际执行了四道检查shfmt 格式化检查以 2 空格缩进、bash 方言检查scripts/*.bash、test/test_helpers.bash以及test/fixtures/dummy_*_plugin/bin/*等文件同时以 bats 方言检查test/*.batsShellCheck 静态分析分别以--shell bash和--shell bats均带--external-sources检查上述同组文件自定义 Python 检查调用 scripts/checkstyle.py该脚本实现了 shellcheck 覆盖不到的团队专属规则例如禁止function fn()写法保持fn() { ... }一致风格、用$PWD替代$(pwd)避免子 shell 开销、用/dev/null替代/dev/null 21、以及禁止[ a b ]中的双等号等。它支持--fix自动修复、--internal-test-regex自检正则并在无 Python3 的本地环境自动跳过fish_indent 检查对internal/completions/asdf.fish做格式化校验对应 fish shell 的补全脚本。脚本开头还会校验当前目录必须是仓库根目录通过git rev-parse --show-toplevel对比否则直接报错退出且必须传入-c/-f/-h之一。目前 elvish、nushell、powershell 的 linter 尚未接入源码中以 TODO 注释保留。test.bash 如何跑全部测试scripts/test.bash 同样强制在仓库根目录执行然后调用 Bats 运行./test目录默认附加--timing --print-output-on-failure两个选项。值得注意的性能优化是如果检测到parallelGNU parallel命令会追加--jobs 2 --no-parallelize-within-files并行执行测试文件以加速若在 CI 环境设置了CI环境变量却没有 parallel则直接报错退出。关于示例命令的小修正core 指南中的示例命令bats test/list_commands.bash在当前的 test/ 目录中并不存在对应的list_commands.bats文件当前测试文件按*_command.bats命名如 test/set_command.bats、test/install_command.bats。实际跑单个测试文件时请按现有文件名执行例如bats test/set_command.bats。这正是以当前仓库实际内容为准的体现。Bats 测试asdf 的测试体系执行与阅读测试本地执行全部测试./scripts/test.bash官方在动手写测试前强烈建议先读三样东西test/目录下已有的测试、bats-core 官方文档以及scripts/test.bash中已有的 Bats 配置。这套测试体系覆盖了 asdf 的所有核心命令从 test/ 目录可以看到install_command.bats、set_command.bats、plugin_add_command.bats、shim_exec.bats、where_command.bats、which_command.bats等一整套按命令组织的测试文件。以 test/set_command.bats 为例可以直观看到 Bats 测试的组织方式setup()中通过test_helpers.bash提供的setup_asdf_dir、install_dummy_plugin、install_dummy_version构建隔离环境teardown()中清理每个test块用run asdf set ...执行命令并断言$status退出码与$output输出例如test set should create .tool-versions file in current directory { run asdf set dummy 1.0.0 [ $status -eq 0 ] [ -f $PROJECT_DIR/.tool-versions ] run cat $PROJECT_DIR/.tool-versions [ $output dummy 1.0.0 ] }test/test_helpers.bash 是这套测试的核心支撑库提供setup_asdf_dir、install_mock_plugin、install_mock_plugin_no_download、install_mock_legacy_plugin、install_mock_broken_plugin等工具函数配合test/fixtures/下的dummy_plugin、dummy_legacy_plugin、dummy_broken_plugin等假插件夹具实现对真实场景的模拟。调试技巧用 TAP 输出打印信息Bats 调试有时相当困难。官方给出的技巧是使用-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普通输出在测试运行时默认被吞掉只有重定向到3的内容才会在bats -t模式下显示到终端。这一行为在 bats-core 的 Printing to the Terminal 一节中有更详细的说明。测试是必需的core 指南中的提示框非常明确新功能必须配测试bug 修复也应通过测试来加速评审。请在创建 Pull Request 之前覆盖新的代码路径。CI 工作流 .github/workflows/tests.yml 也印证了这一点它通过dorny/paths-filter按改动路径文档、CLI、Go 代码分流在 Ubuntu 与 macOS 双平台矩阵上先执行scripts/install_dependencies.bash该脚本会从.tool-versions读取 bats 版本并克隆安装 bats-core同时为 Linux/macOS 安装 elvish、nushell、fish、powershell、parallel 等跨 shell 测试依赖再运行 Go 测试。这意味着你的每个改动都会在多个 shell 与平台上被验证。仓库规范.gitignore 与 .git-blame-ignore-revs.gitignore 的分工仓库根目录的 .gitignore 只忽略项目专属文件当前内容如下/installs /downloads /shims repository .vagrant keyrings /tmp dist/ # ignore build binary asdf可见它覆盖的是 asdf 运行时产生的目录installs、downloads、shims、dist/构建产物以及编译出的asdf二进制。而操作系统、编辑器或工具链特有的文件如编辑器临时文件官方建议放到你的全局.gitignore中避免把个人工作流噪音混入项目提交。.git-blame-ignore-revs让 git blame 更干净asdf使用 .git-blame-ignore-revs 来降低git blame时的噪音——像 Run shfmt on bash files、Remove inside [ 这类纯格式化或机械重构的提交会被忽略让 blame 直接定位到真正改动逻辑的那次提交。使用时手动指定git blame --ignore-revs-file .git-blame-ignore-revs ./test/install_command.bats也可以配置 git 全局启用免去每次手动指定git config blame.ignoreRevsFile .git-blame-ignore-revsIDE 同样可以接入。以 VSCode 配合 GitLens 为例在.vscode/settings.json中写入{ gitlens.advanced.blame.customArguments: [ --ignore-revs-file, .git-blame-ignore-revs ] }Pull Request 与发布Conventional Commits 驱动 Release Please自动化发布机制asdf使用 Google 的 Release Please 生成所有信息都来自自上次发布以来的提交历史。仓库中的 release-please-config.json 证实了这一机制发布类型为gofeat对应 Features、fix对应 Patches、docs对应 Documentation 章节并额外维护 SECURITY.md、各语言版 docs/guide/getting-started.md 及 cmd/asdf/main.go 等文件中的版本占位符。而 Pull Request 标题必须遵循 Conventional Commits。发布流程则由 .github/workflows/release.yml 驱动。提交信息格式Conventional Commits 的标准格式为type[optional scope][optional !]: description !-- 示例 -- 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。各类型对版本号的影响规则如下标记含义触发的版本变更!破坏性变更标记配合 type 使用fix修复 bug新的 SemVerpatchfeat新功能新的 SemVerminortype!破坏性变更新的 SemVermajorPull Request 标题必须严格遵守该格式。文档类改动如修改本文所属的 docs 站点也遵循同样的约定见 docs/contribute/documentation.md文档 PR 的标题应使用docs类型即docs: description。延伸Docker 镜像asdf社区还维护着 asdf-alpine 与 asdf-ubuntu 两个项目提供预装了部分 asdf 工具的 Docker 镜像。你可以把它们作为开发服务器的基底镜像或直接用于运行生产应用——这为在容器化环境里使用 asdf 管理运行时版本提供了现成方案。小结参与 asdf 核心开发的完整链路是Fork 克隆 → 用.tool-versionsasdf install准备工具链 → 通过$ASDF_DIR隔离试运行 → 本地跑./scripts/lint.bash与./scripts/test.bash通过质量门槛 → 编写覆盖新代码路径的 Bats 测试 → 按 Conventional Commits 规范书写 PR 标题 → 由 CI 与 Release Please 自动完成校验、测试、版本发布与变更日志生成。希望本文能帮助你顺利成为 asdf 的贡献者。【免费下载链接】asdfExtendable version manager with support for Ruby, Node.js, Elixir, Erlang more项目地址: https://gitcode.com/GitHub_Trending/as/asdf创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考