asdf

asdf 核心贡献指南.

初始化安装

在 Github 上 fork asdf 并且/或者使用 Git 克隆默认分支：

shell

# 克隆你 fork 的 asdf
git clone https://github.com/<GITHUB_USER>/asdf.git
# 或者直接克隆 asdf
git clone https://github.com/asdf-vm/asdf.git

核心开发所需的工具都列举在这个存储库的 .tool-versions 文件中。如果你想要使用 asdf 自身来管理它，请使用以下命令添加这些插件：

shell

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：

shell

asdf install

在本地机器的开发过程中不使用 asdf 来管理工具或许对你有帮助，因为你可能需要打破某些可能会影响到你的开发工具链的功能。以下是所需工具的原始列表：

bats-core：Bash 自动化测试系统，用于单元测试 Bash 或 POSIX 兼容脚本。
shellcheck：Shell 脚本的静态分析工具。
shfmt：支持 Bash 的 Shell 解析器、格式化器和解释器；包含 shfmt。

开发

如果你想要在不更改已安装的 asdf 的情况下尝试应用你的更改，可以将 $ASDF_DIR 变量设置为克隆存储库的路径，并临时将目录的 bin 和 shims 目录添加到你的路径中。

最好在提交或推送到远程之前，在本地做好格式化、lint 检查和测试你的代码。可以使用以下脚本/命令：

shell

# 脚本检查
./scripts/lint.bash --check

# 格式化
./scripts/lint.bash --fix

# 测试：所有案例
./scripts/test.bash

# 测试：特定命令
bats test/list_commands.bash

提示

增加测试！ - 新特性需要进行测试，并加快错误修复的审查速度。请在创建拉取请求之前覆盖新的代码路径。查看 bats-core 文档了解更多。

Gitignore

以下是 asdf-vm/asdf 仓库中的 .gitignore 文件。我们忽略项目特定的文件。与操作系统、工具或工作流程相关的文件应在全 .gitignore 配置中忽略，请查看此处了解更多。

gitignore

/installs
/downloads
/shims
repository
.vagrant
keyrings
/tmp

dist/

# ignore build binary
asdf

`.git-blame-ignore-revs`

asdf 使用 .git-blame-ignore-revs 文件来减少在运行 blame 命令时的噪音。请查看 git blame documentation 了解更多。

使用 git blame 时，可通过以下方式使用该文件：

git blame --ignore-revs-file .git-blame-ignore-revs ./test/install_command.bats

可选地，配置为在每次调用 blame 时自动使用该文件，无需手动提供：

git config blame.ignoreRevsFile .git-blame-ignore-revs

可以配置集成开发环境（IDEs）使用该文件。例如，在使用 VSCode (搭配 GitLens) 时，将以下内容写入 .vscode/settings.json：

json

{
  "gitlens.advanced.blame.customArguments": [
    "--ignore-revs-file",
    ".git-blame-ignore-revs"
  ]
}

Bats 测试

在本地执行测试：

shell

./scripts/test.bash

在编写测试之前，请务必阅读：

test/ 目录中的现有测试
bats-core 文档
scripts/test.bash 中使用的现有 Bats 设置

Bats 提示

Bats 调试有时可能很困难。使用带有 -t 标识的 TAP 输出将使你能够在测试执行期间打印带有特殊文件描述符 >&3 的输出，从而简化调试。例如：

shell

# 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

进一步相关文档请查看 bats-core 的终端打印部分.

拉取请求、发布以及约定式提交

asdf 正在使用一个名为 Release Please 的自动发布工具来自动碰撞 SemVer 版本并生成变更日志。这个信息是通过读取自上次发布以来的提交历史记录来确定的。

约定式提交定义了拉取请求标题的格式，该标题成为默认分支上的提交消息格式。这是通过 Github Action amannn/action-semantic-pull-request 强制执行的。

约定式提交遵循以下格式：

<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

<types> 的所有类型包含： feat、fix、docs、style、refactor、perf、test、build、ci、chore、revert。

!：表示重大更改
fix：将会创建一个新的 SemVer patch 补丁
feat：将会创建一个新的 SemVer minor 小版本
<type>!：将会创建一个新的 SemVer major 大版本

拉取请求标题必须遵循这种格式。

提示

请使用约定式提交信息格式作为拉取请求标题。

Docker 镜像

asdf-alpine 和 asdf-ubuntu 项目正在努力提供一些 asdf 工具的容器化镜像。你可以使用这些容器镜像作为开发服务器的基础镜像，或者运行生产应用。

asdf ​

初始化安装 ​

开发 ​

Gitignore ​

.git-blame-ignore-revs ​

Bats 测试 ​

Bats 提示 ​

拉取请求、发布以及约定式提交 ​

Docker 镜像 ​

asdf

初始化安装

开发

Gitignore

`.git-blame-ignore-revs`

Bats 测试

Bats 提示

拉取请求、发布以及约定式提交

Docker 镜像