feat: declare the four young layers @experimental, and let @entered be told where to write - #27
Merged
Merged
Conversation
…e told where to write Before this the package had 82 public names and declared 9 of them — the release layer, because its file format was a guess. The four layers that moved *this week* were not declared, which is the state this package exists to make visible in somebody else's code. * **`record`** — `Record` gained a `value` field in #26, after `write_record` already had a file format, so a file written by an earlier version reads back with that field empty. And `paths` and `timing` are refused together because the pair segfaulted 2 runs in 4 where each alone crashed 0 in 4. * **`@entered`** — its report is text with no schema and it changed twice in its first week: the hit lines gained a sort order and column alignment (#26), the footer a singular verb. * **`reach`** — where `:clean` stops and `:unknown` starts is drawn by Julia's own IR accessors, which are internal and differ by minor version: `Base.IRShow.getdebugidx` on 1.12, `codelocs`/`linetable` on 1.11, and `Core.TypeEgal{T}` where earlier versions say `Type{T}`. * **`verify`** — the counts come from `ccall(:jl_write_coverage_data, …)` and the `.cov` line format, neither of which Julia documents. 39 of 82 are now declared, 43 are not. The point of doing this before a release is what the package's own `isbreaking` then says: a declared name can change without the change being breaking, by this package's own definition. Undeclared, it cannot — and `Record` gaining a field one commit ago is not the behaviour of a settled struct. `test/test_dogfood.jl` used to pin the declared set to exactly the release layer's nine names and assert every reason contained "schema". It now carries a per-layer table, and each layer's anchor is a measured detail — "segfault", "getdebugidx", "jl_write_coverage_data" — so a reason that could have been written without doing the measurement fails. The equality against a hand-written set has a failure mode: marking every name and updating the set to match satisfies it. So a second testset asserts the 24 names of the settled core — the three questions the front page promises — are on the surface and are NOT marked. A package that declared everything would be telling you nothing. Also: `@entered io expr`. The report was hardwired to `stdout`, so a caller who wanted it in a log had to redirect the whole process to get at one line. `io` is looked up when the block runs rather than when the macro expands, so the default still follows `redirect_stdout` — and the test's control asserts that naming an `io` MOVES the report rather than copying it. 1192 assertions, green. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Contributor
|
📚 Docs preview: https://codes.sota-shimozono.com/ExperimentalAPI.jl/previews/PR27/ (updates on each push to this PR) |
Codecov Report✅ All modified and coverable lines are covered by tests. 📢 Thoughts on this report? Let us know! |
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.
The package had 82 public names and declared 9 — the release layer, because its file format was a
guess. The four layers that moved this week were not declared. That is exactly the state this
package exists to make visible in somebody else's code.
What is now declared, and the measured reason each carries
record,Record,Hit,write_record, … (13 names)Recordgained avaluefield in #26, afterwrite_recordalready had a file format — a file written by an earlier version reads back with that field empty. Andpaths+timingare refused together because the pair segfaulted 2 runs in 4 where each alone crashed 0 in 4.@enteredreach,Reach,verdict, … (9 names):clean/:unknownline is drawn by Julia's internal IR accessors, which differ by minor:Base.IRShow.getdebugidxon 1.12,codelocs/linetableon 1.11,Core.TypeEgal{T}where earlier versions sayType{T}.verification,coverage,flush_coverage, … (7 names)ccall(:jl_write_coverage_data, …)and the.covline format. Julia documents neither.39 of 82 declared, 43 not.
Why before a release rather than after
The package's own
isbreakingis the arbiter. A declared name can change without the change beingbreaking by this package's own definition; an undeclared one cannot.
Recordgaining a field onecommit ago is not the behaviour of a settled struct, and shipping it undeclared would lock it.
The test that used to say the opposite
test/test_dogfood.jlpinned the declared set to exactly the release layer's nine names andasserted every reason contained
"schema"— i.e. it encoded "the release layer is the only youngone", which this PR falsifies. It now carries a per-layer table whose anchor is a measured
detail (
"segfault","getdebugidx","jl_write_coverage_data"), so a reason that could havebeen written without doing the measurement fails.
An equality against a hand-written set has one failure mode: mark every name, update the set,
green. So a second testset asserts the 24 names of the settled core —
@experimental,entered,audit,mark,surface, … — are on the surface and are not marked. A package that declaredeverything would be telling you nothing.
Also:
@entered io exprThe report was hardwired to
stdout, so a caller who wanted it in a log had to redirect the wholeprocess to get at one line.
ioresolves when the block runs, not when the macro expands, so thedefault still follows
redirect_stdout; the test's control asserts naming aniomoves thereport rather than copying it.
1192 assertions, green.
🤖 Generated with Claude Code