Hi, we've recently migrated our docs and added some new pages. If you would like to help translate this page, see the "Edit this page" link at the bottom of the page.
asdf core contribution guide.
asdf on GitHub and/or Git clone the default branch:
# clone your fork git clone https://github.com/<GITHUB_USER>/asdf.git # or clone asdf git clone https://github.com/asdf-vm/asdf.git
The tools for core development are in this repo's
.tool-versions. If you wish to manage with
asdf itself, add the plugins:
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
Install the versions to develop
It may be useful to not use
asdf to manage the tools during development on your local machine as you may need to break functionality which would then break your dev tooling. Here's the raw list of tools:
- bats-coreopen in new window: Bash Automated Testing System, for unit testing Bash or POSIX compliant scripts.
- shellcheckopen in new window: Static analysis tool for shell scripts.
- shfmtopen in new window: A shell parser, formatter, and interpreter with bash support; includes shfmt
If you want to try out your changes without making change to your installed
asdf, you can set the
$ASDF_DIR variable to the path where you cloned the repository, and temporarily prepend the
shims directory of the directory to your path.
It is best to format, lint and test your code locally before you commit or push to the remote. Use the following scripts/commands:
# Shellcheck ./scripts/shellcheck.bash # Format ./scripts/shfmt.bash # Test: all tests bats test/ # Test: for specific command bats test/list_commands.bash
Add tests! - Tests are required for new features and speed up review of bug fixes. Please cover new code paths before you create a Pull Request. See bats-core documentationopen in new window
It is strongly encouraged to examine the existing test suite and the bats-core documentationopen in new window before writing tests.
Bats debugging can be difficult at times. Using the TAP output with
-t flag will enable you to print outputs with the special file descriptor
>&3 during test execution, simplifying debugging. As an example:
# 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
This is further documented in bats-core Printing to the Terminalopen in new window.
Pull Requests, Releases & Conventional Commits
asdf is using an automated release tool called Release Pleaseopen in new window to automatically bump the SemVeropen in new window version and generate the Changelogopen in new window. This information is determined by reading the commit history since the last release.
Conventional Commit messagesopen in new window define the format of the Pull Request Title which becomes the commit message format on the default branch. This is enforced with GitHub Action
amannn/action-semantic-pull-requestopen in new window.
Conventional Commit follows this format:
<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
The full list of
! indicates a breaking change.
fix: will create a new SemVer
feat: will create a new SemVer
<type>!: will create a new SemVer
The Pull Request Title must follow this format.
Use Conventional Commit message format for your Pull Request Title.
The asdf-alpineopen in new window and asdf-ubuntuopen in new window projects are an ongoing effort to provide Dockerized images of some asdf tools. You can use these docker images as base for your development servers, or for running your production apps.