Skip to content

docs: fix broken nix command and stale references in contributor docs - #6129

Merged
max-sixty merged 1 commit into
mainfrom
docs/dev-docs-stale-refs
Aug 3, 2026
Merged

docs: fix broken nix command and stale references in contributor docs#6129
max-sixty merged 1 commit into
mainfrom
docs/dev-docs-stale-refs

Conversation

@prql-bot

@prql-bot prql-bot commented Aug 3, 2026

Copy link
Copy Markdown
Collaborator

Four stale or incorrect references in the contributor docs, each checked against the code or run in a shell.

web/book/src/project/contributing/development.md

The nix setup command doesn't work. Step 2 of "Option 4: Use nix development environment" says tee 'experimental-features = nix-command flakes' >> ~/.config/nix/nix.conf. tee's argument is a filename, not content — so this creates a file literally named experimental-features = nix-command flakes in the current directory, blocks reading stdin from the terminal, and leaves nix.conf empty. Anyone following the nix path today gets no flakes and a junk file. Changed to echo.

Python version is two releases behind. The doc says "ensure we have Python >= 3.7"; prqlc-python/pyproject.toml declares requires-python = ">=3.9".

"GitHub Actions on merge" points at a deleted workflow. The link was SHA-pinned to c042eef4's .github/workflows/pull-request.yaml#L124; that file no longer exists on main. Push-to-main test runs are now tests.yaml, which declares push: branches: [main] and gates the wider matrix through the rules job's main output — so the surrounding prose still describes real behavior, just via a different file. Repointed to tests.yaml. Left unpinned deliberately: it's a whole-file reference with no line anchor, and the intent is "wherever this lives now".

CLAUDE.md

Integration test path is missing a directory level. It reads prqlc/tests/integration/queries/*.prql; the actual location is prqlc/prqlc/tests/integration/queries/. prqlc/tests/ doesn't exist. Same class of slip as #6108, one directory up.

The doc-viewing snippet invokes a View tool that doesn't exist. Claude Code's file-reading tool is Read; there is no View. Following the snippet as written fails.

Verification

The tee behavior, run in a scratch directory:

$ cd /tmp/teetest && tee 'experimental-features = nix-command flakes' >> ./nix.conf < /dev/null
$ ls -la
-rw-rw-r-- 1 ... 0 ... 'experimental-features = nix-command flakes'
-rw-rw-r-- 1 ... 0 ... nix.conf

Both files are 0 bytes — the setting never reaches nix.conf. (< /dev/null stands in for the terminal here; interactively it would hang instead.)

Paths:

$ test -d prqlc/tests/integration/queries        # absent
$ test -d prqlc/prqlc/tests/integration/queries  # present
$ ls .github/workflows/ | grep pull-request
pull-request-target.yaml

requires-python is read directly from pyproject.toml (linked above).

No regression test. These are all prose and link fixes with no executable surface; the shell transcripts above are the check. The one testable claim — the missing directory level in CLAUDE.md — is verified by the test -d pair.

@max-sixty
max-sixty merged commit 510bb5e into main Aug 3, 2026
36 checks passed
@max-sixty
max-sixty deleted the docs/dev-docs-stale-refs branch August 3, 2026 20:36
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants