asdf ​

これは、asdfコアのコントリビューションガイドです。

初期セットアップ ​

GitHubでasdfをフォークするか、デフォルトのブランチをGitクローンしてください:

# clone your fork
git clone https://github.com/<GITHUB_USER>/asdf.git
# or clone asdf
git clone https://github.com/asdf-vm/asdf.git

# clone your fork
git clone https://github.com/<GITHUB_USER>/asdf.git
# or clone asdf
git clone https://github.com/asdf-vm/asdf.git

コア開発用のツールは、このリポジトリの.tool-versionsで定義されています。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 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の開発に必要なバージョンを、下記のようにインストールします:

asdf install

asdf install

開発ツールに影響を与える特定の機能を壊す可能性もあるため、ローカルマシンで開発する際は、asdfを使用しないほうが 良いかもしれません 。下記に、使用しているツールを列挙します:

• bats-core: BashまたはPOSIX準拠のスクリプトを単体テストするための、Bash自動テストシステムです。
• shellcheck: シェルスクリプトの静的解析ツールです。
• shfmt: Bashをサポートするシェルパーサ、フォーマッタ、インタプリタです。

開発 ​

インストール済みのasdfに変更を加えずに、あなたが開発した変更内容を試したいときは、$ASDF_DIR変数に、クローンしたリポジトリのパスを設定し、そのディレクトリのbinとshimsディレクトリを一時的にパスの先頭へ追加します。

リモートにコミットまたはプッシュする前に、コードをローカルでフォーマット、Lint、およびテストすることを推奨します。その際は、次のスクリプト/コマンドを使用してください:

# Lint
./scripts/lint.bash --check

# Fix & Format
./scripts/lint.bash --fix

# Test: all tests
./scripts/test.bash

# Test: for specific command
bats test/list_commands.bash

# Lint
./scripts/lint.bash --check

# Fix & Format
./scripts/lint.bash --fix

# Test: all tests
./scripts/test.bash

# Test: for specific command
bats test/list_commands.bash

Gitignore ​

下記は、asdf-vm/asdfリポジトリの.gitignoreファイルです。プロジェクト固有のファイルは無視をしています。使用しているOS、ツール、およびワークフロー固有のファイルは、グローバルな.gitignore構成で無視する必要があります。詳しくはこちらをご覧ください。

@Gitignoreコード

.git-blame-ignore-revs ​

asdfでは、.git-blame-ignore-revsを使用して、Blameを実行する際のノイズを減らしています。詳しくは、git blameのドキュメントをご覧ください。

git blameを実行するときは、下記のように、このファイルと共に使います:

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

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

毎回手動でファイルを指定しなくても、gitのオプションで、blameを呼び出すたびにこのファイルを使うように設定することもできます:

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

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

このファイルを使用するように、IDEを設定することもできます。例えば、VSCode(およびGitLens)を使う場合は、.vscode/settings.jsonに下記のように記述します:

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

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

Batsテスト ​

ローカルでテストを実行するには、下記のようにテストを呼び出します:

./scripts/test.bash

./scripts/test.bash

テストを作成する前に、下記項目を一通り参照してください:

• test/内にすでに作成されているテスト
• bats-coreのドキュメント
• scripts/test.bashで使用されている既存のBatsの設定

Batsのヒント ​

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

# 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ドキュメント内のPrinting to the Terminalで説明されています。

プルリクエスト、リリース、Conventional Commits ​

asdfは、Release Pleaseという自動リリースツールを使用して、セマンティックバージョンを自動的に引き上げ、Changelogを生成しています。この情報は、前回のリリースからのコミット履歴を読み込むことで生成されます。

Conventional Commit messagesでは、デフォルトブランチでのコミットメッセージのフォーマットとなる、プルリクエストタイトルのフォーマットを定義しています。これは、GitHub Actionamannn/action-semantic-pull-requestで強制されます。

Conventional Commitは、下記のフォーマットに従います:

<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>[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

<types>の種類は次のとおりです: feat、fix、docs、style、 refactor、 perf、test、build、ci、chore、 revert。

• !: 破壊的変更を示します
• fix: セマンティックバージョンのpatchを新しく作成します
• feat: セマンティックバージョンのminorを新しく作成します
• <type>!: セマンティックバージョンのmajorを新しく作成します

プルリクエストのタイトルは、このフォーマットに従う必要があります。

Dockerイメージ ​

asdf-alpineおよびasdf-ubuntuプロジェクトは、一部のasdfツールのDocker化されたイメージを提供する取り組みを継続的に行っています。これらのDockerイメージは、開発用サーバのベースとしたり、本番用アプリケーションの実行用途として使用することができます。