Define & Document supported Shells & OSs
- Dominant language
- Go
- Stars
- 25.6k
- Forks
- 941
- Avg merge
- 9h 24m
- Merged PRs (30d)
- 3
Description
### How can we improve the documentation?
We only list support for Bash, ZSH, Fish & Elvish. We do not list Bash as a dependency, *which it certainly is*. This lack of clarity leads to many conversations on the matter (see related list below). It has also lead to issues being masked due to suboptimal configuration of automated code quality tooling ([#1396](https://github.com/asdf-vm/asdf/issues/1396) & [#1397](https://github.com/asdf-vm/asdf/issues/1397)). We should document what we support or discuss this decision concretely if not at a consensus ([I think asdf core do agree](https://github.com/asdf-vm/asdf/issues/1313#issuecomment-1348640247), though we have never been forced to decide).
## What Bash versions should we support
I think we should commit to the same versions as Bats & Shellcheck as we're using those to validate asdf already.
Bats list their supported versions:
```
Bash versions:
- Everything from 3.2.57(1) and higher (macOS’s highest version)
Operating systems:
- Arch Linux
- Alpine Linux
- Ubuntu Linux
- FreeBSD 10.x and 11.x
- macOS
- Windows 10
Latest version for the following Windows platforms:
- Git for Windows Bash (MSYS2 based)
- Windows Subsystem for Linux
- MSYS2
- Cygwin
```
Our OS support is nowhere near this yet(tm).
## Which code should be considered for which shells?
Entrypoints:
- Elvish:
- `asdf.elv`
- Fish:
- `asdf.fish`
- `lib/asdf.fish`
- Bash/ZSH
- `asdf.sh`
- `lib/asdf.sh`
- Nushell
- `asdf.nu`
The following is used regardless of Shell, but interpretted by Bash (or system `sh`? I don't quite know):
- `lib/utils.bash`
- `lib/commands/*.bash`
- `lib/functions/*.bash`
Tests should also be considered:
- Bash
- `test/test_helpers.bash`
- Bats (yes this is different to Bash)
- `test/*.bats`
## Supported?
We should document what it means for asdf to _support_ a Shell or OS. I propose that for some Shell or OS to be _supported_ we must:
1. have some CI to validate basic usage
1. define a minimum version
This is important because asdf currently works in some places we don't actually test for.
## To resolve
What should we do to resolve this:
- [ ] document what it means to "support" a Shell or OS
- [ ] document Bash as a dependency in our "Getting Started" page
- with 3.2 as the minimum supported version (macOS :eye_roll:)
- [ ] ensure we're testing against Bash 3.2 (latest for v3)
- [ ] test against Bash 4.4 (latest for v4)
- [ ] test against Bash 5.2 (latest)
- [ ] document other Shells minimum supported versions
- [ ] test against these minimum supported versions
- [x] enable linting for the appropriate codebase areas as in
- #1396
- #1397
## Related
Improve code quality (using Bash)
- https://github.com/asdf-vm/asdf/issues/160
- https://github.com/asdf-vm/asdf/issues/520
- https://github.com/asdf-vm/asdf/issues/817
- https://github.com/asdf-vm/asdf/issues/1313
- https://github.com/asdf-vm/asdf/issues/1349
- https://github.com/asdf-vm/asdf/issues/1435
Other shells:
- https://github.com/asdf-vm/asdf/issues/450
- https://github.com/asdf-vm/asdf/issues/576
- https://github.com/asdf-vm/asdf/issues/653
OSs:
- https://github.com/asdf-vm/asdf/issues/465
Contributor guide
Assessment
This issue has not been assessed yet.