Skip to content

Commit 1128abd

Browse files
committed
docs: describe Flox in our own voice, not a third party's
Several passages described Flox the way an outsider describes another company's product: "the flox packages ship their own Nix", "flox brings its own Nix". We maintain Flox, so the possessive framing is wrong. The distinction is between "ships their own Nix", which is what an observer writes, and "ships with Nix", which is what the maintainer writes. Most of these are prose, but one is not. The string in `core.warning` that fires when reinstalling from a reference with no version ordering is printed into the user's job log, and the `version` input description in `action.yml` appears in the Marketplace listing. The README passages render on the repository page. The remaining three are comments that no user sees, corrected for consistency. That warning also opened with a sentence fragment, and "afterwards" is now "afterward". Nothing behavioral changes. `dist/index.js` is regenerated because these strings live in the bundle.
1 parent 9723f84 commit 1128abd

5 files changed

Lines changed: 28 additions & 28 deletions

File tree

README.md

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -134,9 +134,9 @@ GitHub-hosted runners start every job on a fresh machine. Self-hosted runners, a
134134

135135
**The runner needs `sudo` and `xz` present first.** Both are pre-dependencies of the flox `deb` and `rpm`, and `sudo` is needed regardless of how flox is installed, since this action uses it to write the Nix configuration. GitHub's hosted images carry both; a minimal self-hosted machine may not, in which case installation fails on the missing dependency and retries until it gives up. Install them as part of provisioning the runner.
136136

137-
**It looks for flox before it looks for Nix.** The flox packages ship their own Nix and symlink it into `/usr/bin`, so a runner that has already installed flox has a `nix` on `PATH` that this action put there. Checking for `flox` first tells the two situations apart. When flox is already present the installation is skipped, `flox-preinstalled` is set to `true`, and the run costs nothing beyond the configuration steps. Set `force-reinstall: true` to install the channel's current release on every run instead, or pin `version` to reinstall whenever the pinned version is newer than the one already installed.
137+
**It looks for flox before it looks for Nix.** Installing flox also installs Nix, symlinked into `/usr/bin`, so a runner that has already installed flox has a `nix` on `PATH` that this action put there. Checking for `flox` first tells the two situations apart. When flox is already present the installation is skipped, `flox-preinstalled` is set to `true`, and the run costs nothing beyond the configuration steps. Set `force-reinstall: true` to install the channel's current release on every run instead, or pin `version` to reinstall whenever the pinned version is newer than the one already installed.
138138

139-
**Downgrading in place fails with an error.** Flox brings its own Nix, and a Nix store cannot be read by a Nix older than the one that last wrote it, so installing an older flox over a newer one leaves a machine that breaks at first use rather than at install time. No package manager refuses the swap on those grounds, so the action checks before installing and stops. To move a runner back to an older version, remove flox and `/nix` from it and install again. A reference with no version ordering, a commit-hash channel for instance, cannot be checked this way; those are allowed through with a warning.
139+
**Downgrading in place fails with an error.** Flox ships with Nix, and a Nix store cannot be read by a Nix older than the one that last wrote it, so installing an older flox over a newer one leaves a machine that breaks at first use rather than at install time. No package manager refuses the swap on those grounds, so the action checks before installing and stops. To move a runner back to an older version, remove flox and `/nix` from it and install again. A reference with no version ordering, a commit-hash channel for instance, cannot be checked this way; those are allowed through with a warning.
140140

141141
**It writes its Nix configuration fresh for every job.** The action writes its settings to a file under `/etc/nix/` named for the job that owns them, `install-flox-action-<run>-<attempt>-<id>.conf`, and adds one matching `!include` line to `/etc/nix/nix.conf`. A new file each job means the recorded `github-token` is never the expired one from a previous job, and it means a machine running several jobs at once gives each its own file: a shared one would let the first job to finish delete a token another job is still using. The post step removes this job's file and, with it, any include line whose file is gone, so a job killed before its post step ran does not leave litter behind. A stale token is worse than no token: Nix falls back to anonymous, rate-limited access when none is configured, but fails outright with `HTTP error 401` when it finds one that has expired.
142142

action.yml

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -12,8 +12,8 @@ inputs:
1212
description: >-
1313
Select a specific version from a channel. Installing a
1414
version older than the one already on the runner fails:
15-
flox brings its own Nix, which cannot read a store
16-
written by a newer one.
15+
flox ships with Nix, which cannot read a store written
16+
by a newer one.
1717
default: ""
1818

1919
channel:

dist/index.js

Lines changed: 11 additions & 11 deletions
Some generated files are not rendered by default. Learn more about customizing how changed files appear on GitHub.

src/main.js

Lines changed: 11 additions & 11 deletions
Original file line numberDiff line numberDiff line change
@@ -362,10 +362,10 @@ async function run() {
362362

363363
core.startGroup('Download & Install flox')
364364

365-
// The flox packages symlink their own Nix into /usr/bin, so on a runner
366-
// whose disk survives the job, `nix` alone cannot tell a Nix the user
367-
// brought from the one an earlier run of this action installed. Asking
368-
// for flox first answers the question directly.
365+
// Installing flox also installs Nix, symlinked into /usr/bin, so on a
366+
// runner whose disk survives the job, `nix` alone cannot tell a Nix the
367+
// user brought from the one an earlier run of this action installed.
368+
// Asking for flox first answers the question directly.
369369
const floxPath = await which('flox', { nothrow: true })
370370
const nix = await which('nix', { nothrow: true })
371371
const nixDetected = nix !== null
@@ -377,7 +377,7 @@ async function run() {
377377
if (floxPath !== null) {
378378
installedVersion = await getInstalledVersion()
379379

380-
// Flox brings its own Nix, and a Nix store database migrates only
380+
// Flox ships with Nix, and a Nix store database migrates only
381381
// forward: a Nix older than the one that last wrote the store can refuse
382382
// to operate against it. No package manager declines the swap on those
383383
// grounds, so the install would succeed and the machine would break
@@ -404,12 +404,12 @@ async function run() {
404404
!isOrderable(requestedVersion, installedVersion)
405405
) {
406406
core.warning(
407-
'Reinstalling flox over an existing installation from a reference ' +
408-
'with no version ordering, so this may be a downgrade. Downgrading ' +
409-
'in place is not supported: flox brings its own Nix, and a Nix ' +
410-
'store cannot be read by a Nix older than the one that last wrote ' +
411-
'it. If anything fails against /nix afterwards, remove flox and ' +
412-
'/nix from the runner and install again.'
407+
'This reinstalls flox over an existing installation from a ' +
408+
'reference with no version ordering, so it may be a downgrade. ' +
409+
'Downgrading in place is not supported: flox ships with Nix, ' +
410+
'and a Nix store cannot be read by a Nix older than the one ' +
411+
'that last wrote it. If anything fails against /nix afterward, ' +
412+
'remove flox and /nix from the runner and install again.'
413413
)
414414
}
415415
}

src/main.test.js

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -103,10 +103,10 @@ describe('main', () => {
103103
expect(core.setOutput).toHaveBeenCalledWith('nix-detected', 'true')
104104
})
105105

106-
// Issue #191: the flox packages symlink their own nix into /usr/bin, so a
106+
// Issue #191: installing flox also installs nix into /usr/bin, so a
107107
// second run on a runner with a persistent disk finds a nix that this
108108
// action installed and mistakes it for one the user brought.
109-
it('skips installation when flox is already present alongside its own nix', async () => {
109+
it('skips installation when flox is already present alongside the nix it installed', async () => {
110110
mockWhich({ nix: '/usr/bin/nix', flox: '/usr/bin/flox' })
111111
core.getInput.mockImplementation(name => {
112112
if (name === 'channel') return 'stable'

0 commit comments

Comments
 (0)