asdf-vm / asdf-vm/asdf

Define & Document supported Shells & OSs

Open
#1,436 5 comments 0 reactions 2 assignees Claimed by @jthegedus View on GitHub
enhancement priority
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

Open the contributing guide

Assessment

This issue has not been assessed yet.

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.