Document what projectUri actually contributes - #98
Open
davidanthoff wants to merge 1 commit into
Open
Conversation
`project_uri`/`projectUri` was described only as "a custom project", and in the JSON-RPC `TestEnvironment` table not at all — four description cells were empty and `color` was missing entirely. That leaves the load-bearing fact undocumented: the project supplies version pins, never dependencies, because the test environment is built from the package's test target. A reader is left to conclude that adding a dependency to a custom project makes it importable, which is the misunderstanding behind #97. Also corrected: - `internals.md` said the child process "activates the package environment", in the state table and in the wire-protocol table. That is precisely what it goes out of its way not to do; it mirrors the source environment into a nameless scratch environment and then lets TestEnv replace the active project again. - The `ProcessEnv` field list omitted `check_bounds` and `color`, both of which are part of process identity. - `scratch_env.jl` claimed the copied manifest makes the environment resolve "against exactly the versions the user has pinned" — true only within the test target's closure, which is all `sandbox_preserve` keeps. - The "Unable to load the `Test` package" message named only `Project.toml`, sending a user who has a `test/Project.toml` to the wrong file. `internals.md` gained an "Environment activation" section: stage 3 of the run lifecycle was one clause of prose, and TestEnv appeared in the whole manual once, as a name in the vendoring list. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
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
1 participant
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.
Doc audit prompted by #97, where a user put a
Project.toml+Manifest.tomlintest/special/,deved the package into it, addedAqua, and expectedusing Aquato work in the test items under it.The behaviour is correct —
projectUrisupplies version pins, and the test environment is built from the package's test target — but this repo never said so.project_uriwas described as "a custom project" and nothing more, which reads as "a custom project supplies the dependencies".Changes
src/datatypes.jl—project_urinow states that it supplies the manifest's version pins, thatnothingmeans the package folder is the source, and that its[deps]do not become importable because the environment comes from the package's test target.docs/src/jsonrpc-api.md— same wording forprojectUri; theTestEnvironmenttable had empty description cells forpackageName,packageUri,projectUriandenvContentHash, and was missingcolor(which is on the wire atsrc/json_protocol.jl:22).docs/src/internals.md— the process-state table and the wire-protocol table both said the child "activates the package environment". That is exactly what it does not do: it mirrors the source environment into a nameless scratch environment, and TestEnv then replaces the active project with a sandbox of its own. Also added an Environment activation section — stage 3 of the run lifecycle was a single clause, andTestEnvappeared in the manual once, as a name in the vendoring list.docs/src/internals.md— theProcessEnvfield list omittedcheck_boundsandcolor, both part of process identity persrc/testenvironment.jl:35-37.scratch_env.jl— "resolves against exactly the versions the user has pinned" overstates it;sandbox_preserveprunes the manifest to the test target's closure, so pins outside it have no effect.TestItemServer.jl— the "Unable to load theTestpackage" message named onlyProject.toml, sending a user who has atest/Project.tomlto the wrong file.The user-facing explanation of the selection rules lives on the docs site; see julia-testitems/julia-testitems.github.io#9, which adds the nested-project section this links to.
Checks
julia --project=docs docs/make.jlexits 0 with only the pre-existing "141 docstrings not included in the manual" warning. Suite is 229/229 — one run hit a transient depot-levelIOError: stat(...registries\$0HIR.pid.deleted): permission denied (EACCES)during activation, unrelated to these changes, and passed on rerun.🤖 Generated with Claude Code