Define & Document supported Shells & OSs

[jthegedus]

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 & #1397). We should document what we support or discuss this decision concretely if not at a consensus (I think asdf core do agree, 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
2. 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
• enable linting for the appropriate codebase areas as in
  • bug: enable shellcheck on bats tests #1396
  • bug: enable shellcheck & shfmt for asdf entrypoints #1397

Related

Improve code quality (using Bash)

• Use set -o nounset -o pipefail -o errexit on top/in all scripts #160
• WIP: Bash Strict Mode #520
• Bash Strict Mode: Part 1 of 3 #817
• Improve consistency with bash syntax #1313
• refactor: Improve Bash Syntax #1349
• docs: track full list of asdf dependencies #1435

Other shells:

• Windows support? Docs & tests for WSL2 #450
• Add support for powershell core #576
• Support for sh/dash #653

OSs:

• Failing tests on windows. #465

[hyperupcall]

I mentioned brefiely here that environments like MinGW, MSYS, and Cygwin should not be explicitly supported. On Windows, WSL2 is no longer available to only insiders and now more closely mirrors what a Linux environment would usually look like with the introduction of systemd support (which makes it so that dbus works, $XDG_RUNTIME_DIR is created, etc.).

So my vote is to remove anything MinGW / Cygwin / MSYS / WSL1 from any potential support matrix in favor of only "Windows via WSL2" support. Other reasons why not to use Cygwin etc. is that they're extremely slow, and it'll take ages for CI to complete with it.

[jthegedus]

Support for WSL1 is a "no go" for me too.

MinGW/Cygwin are tentative as per other discussions in #450. Though not a priority.

I don't want to add WSL2 support to the docs until we get automation testing it, otherwise we'll be opening ourselves up to committing to support a platform we cannot reliable run regression tests against. We are effectively already in this situation, but that was an accident. I don't want to opt into further accidents.

[hyperupcall]

I don't want to add WSL2 support to the docs until we get automation testing it, otherwise we'll be opening ourselves up to committing to support a platform we cannot reliable run regression tests against.

You're right, needlessly opening cans of works makes things more difficult.

We are effectively already in this situation, but that was an accident. I don't want to opt into further accidents.

By this, I assume you are referring to supporting POSIX Shell, or a something else? I read it as WSL2 would be the further accident.

[jthegedus]

By this, I assume you are referring to supporting POSIX Shell, or a something else?

I was more referring to people expecting Windows support given at some point in the past there was a Issue to support Windows and closed by an Appveyor CI setup in a PR. So after that point people consider Windows as tested against and supported, despite it never actually properly validating the same set of tests.

Saying we support WSL2 when we aren't prepared for it would be the mistake, as was merging Appveyor CI in the past.

[airtonix]

there's also https://win-bash.sourceforge.net/