bazelbuild / bazelbuild/bazelisk

Steps for installing Bazelisk are not new-developer friendly

Open
#571 4 comments 24 reactions 0 assignees View on GitHub
P3 type: feature request
Dominant language
Go
Stars
2.7k
Forks
424
PR merge metrics
No merged PRs in 30d

Description

The [current instructions for installing Bazelisk](https://github.com/bazelbuild/bazelisk/tree/24935f4ce663d6eb79e428005b763c059b508866?tab=readme-ov-file#installation) are not user-friendly.

Generally, the widely expected ways to get a tool on the following platforms are:

- Windows: Download an `.exe` installer that guides users through installation.
- macOS: Download .deb or .pkg that guides users through installation.
- Linux: `apt get install bazelisk` or similar through a preferred package manager.

Today, the instructions are:

- Windows: `choco install bazelisk`
- macOS: `brew install bazelisk`
- Linux: There's essentially a decision tree here.

Often, when I direct people to install Bazel via https://bazel.build/install, they end up directly using a release of Bazel rather than Bazelisk. I know the reason I've done this in the past is because of the lack of clarity in the installation process for Bazelisk.

- On macOS, I don't use brew (I've had it corrupt frequently for various reasons, so I now avoid it entirely).
- On Windows, I've never once used or installed choco despite doing a decent amount of development on Windows.
- On Linux, I know how to take a binary and add it to `PATH`, but I know for a fact that someone just getting started with development would stumble over that.

Generally speaking, the recommended flows for installing Bazelisk are atypical at best, and frustrating at worst. Bazelisk should strive to make the installation experience as frictionless as possible to ensure Bazel is approachable for new developers.

Contributor guide

Open the contributing guide

Research direction

Start with the Bazelisk README's Installation section linked in the issue and review the current Windows, macOS, and Linux guidance. Compare the listed Chocolatey, Homebrew, and Linux decision-tree flows with the requested platform expectations. Done should mean that new developers can find clear, frictionless installation paths without accidentally choosing a Bazel release.

Written by the indexing model from the issue text.

Assessment

Domain
documentation, tooling
Issue type
Documentation
Difficulty
4/5
Estimated time
3-5 days
Activity status
Stale
Clarity
Needs clarification
Newbie friendliness
28/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.