docs: restructure install paths around user intent - #599
Open
viniciusdc wants to merge 3 commits into
Open
Conversation
Reorganize the README install section by how people actually install nic: pixi (recommended, pending the prefix.dev channel), Homebrew, release archives with signature verification, and from-source for contributors. Scope the Go 1.26+ prerequisite to source builds only. Draft: the pixi path depends on #579, the install-script and Homebrew sections overlap #539, and the docs-site mirror is still pending. Part of #563.
The pixi commands were written against intent rather than a working channel, and two of the three were wrong: pixi add takes no --channel flag, and the channel is our own rather than the shared github-releases one. Both forms are now the ones verified against the published package. Leads on the Nebi starter workspace, since that is the path where the toolchain and the config pin together, and names the Homebrew cask with --cask so it resolves.
viniciusdc
marked this pull request as ready for review
September 1, 2026 15:46
viniciusdc
requested review from
aktech,
dcmcand,
marcelovilla,
oldsj and
tylerpotts
as code owners
September 1, 2026 15:46
viniciusdc
force-pushed
the
docs/pixi-install-paths-563
branch
from
September 1, 2026 15:47
232b1c9 to
e702f67
Compare
The recommended path's second command could not work: nebi import extracts into the current directory, so `cd local` failed for every reader. It now passes -o explicitly. Deploy was left describing a source checkout while the section above it had just added five other ways to install, so `./nic` and the `cp examples/...` block were wrong for most readers - and the copy would have clobbered the config.yaml the starter ships. Deploy now says which invocation belongs to which install. Also: name the nebi floor, since older versions ship a partial workspace with no error; correct the archive naming, which claimed .tar.gz for Windows and hid that the version carries no leading v; and drop -c conda-forge, which nothing needs - the package has no dependencies. packaging.md and the starter template both still said the channel was empty and the dependency would not resolve. It does.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Part of #563.
What
Restructures the README install section around user intent instead of leading with "build from source":
pixi.lock) or as a machine-wide CLI.### Deploynow says which invocation belongs to which install. It described a source checkout, which was correct whilemake buildwas the only documented path and wrong for five of the six paths this PR adds.Why the commands changed since the draft
The draft documented intent. With the channel and the starters published, every command was run, and several were wrong:
nebi importextracts into the current directory (-odefaults to"."), so the draft'scd localfailed for every reader. Now passes-o local.pixi addhas no--channelflag - the draft's form fails withunexpected argument '--channel' found. The channel goes into the manifest first, viapixi workspace channel add.github-releasesone.nicis onhttps://prefix.dev/nebari-dev/nebari. Moving to the shared channel is Move nic to the shared prefix.dev github-releases channel and delete the bridge #620.brew install --cask..tar.gz- Windows ships.zip,<os>rendersdarwinrather thanmacos, and<version>carries no leadingv.nebineeded a floor. Below 0.10.5 the import silently produces onlypixi.tomlandpixi.lock- noconfig.yaml- so the promise next to it was false with no error. CI pins>=0.13; that is what the README now installs. (release.yml's adjacent comment claims a 0.10 floor and is itself inaccurate.)-c conda-forgewas unnecessary. The package has no dependencies (depends: []on every platform), and bothpixi lockandpixi global installresolve against our channel alone.Two docs corrected alongside
docs/operations/packaging.mdandstarters/templates/pixi.toml.tmplboth stated that the channel was empty and that thenicdependency would not resolve until the first pipeline-driven release. v0.14.0 was seeded by hand and resolves today, so with this PR telling readers to install from that channel the repo asserted both things at once. The template ships inside every generated starter, so it is the one that mattered.How to test
And the project-scoped path:
Both verified on linux-64 against the published v0.14.0.
pixi global installwas verified without-c conda-forge. The Homebrew cask was checked against.goreleaser.ymland theCasks/nic.rbinnebari-dev/homebrew-taprather than run, since it is macOS-only.Scope
Two items on #563 are deliberately not here, which is why this is
Part ofrather thanCloses:starters/templates/README.local.mdandREADME.aws.mdstill only say "Install the pinned toolchain:pixi install". Small, but it belongs with whatever next touches those templates.Two follow-ups this PR deliberately leaves to #539, which is already editing both files and would conflict:
.goreleaser.yml'srelease.headerrendersbrew install nebari-dev/tap/nicinto every release body - the formula form this PR replaces. scripts: add standalone install.sh for the nic binary #539 re-adds it, so the--caskfix belongs there.docs/operations/verifying-releases.mdnumbers integrity before signature, the reverse of the order this README makes load-bearing. scripts: add standalone install.sh for the nic binary #539 has a hunk on that exact heading.