Skip to content

feat: declare the four young layers @experimental, and let @entered be told where to write - #27

Merged
sotashimozono merged 1 commit into
mainfrom
feat/declare-the-young-layers
Sep 8, 2026
Merged

feat: declare the four young layers @experimental, and let @entered be told where to write#27
sotashimozono merged 1 commit into
mainfrom
feat/declare-the-young-layers

Conversation

@sotashimozono

Copy link
Copy Markdown
Member

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

layer why it is not settled
record, Record, Hit, write_record, … (13 names) Record gained a value field in #26, after write_record already had a file format — a file written by an earlier version reads back with that field empty. And paths+timing are refused together because the pair segfaulted 2 runs in 4 where each alone crashed 0 in 4.
@entered text report, no schema, changed twice in its first week — sort order and column alignment (#26), singular verb in the footer.
reach, Reach, verdict, … (9 names) the :clean/:unknown line is drawn by Julia's internal IR accessors, which differ by minor: Base.IRShow.getdebugidx on 1.12, codelocs/linetable on 1.11, Core.TypeEgal{T} where earlier versions say Type{T}.
verification, coverage, flush_coverage, … (7 names) counts come from ccall(:jl_write_coverage_data, …) and the .cov line format. Julia documents neither.

39 of 82 declared, 43 not.

Why before a release rather than after

The package's own isbreaking is the arbiter. A declared name can change without the change being
breaking by this package's own definition; an undeclared one cannot. Record gaining a field one
commit 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.jl pinned the declared set to exactly the release layer's nine names and
asserted every reason contained "schema" — i.e. it encoded "the release layer is the only young
one", 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 have
been 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 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 resolves when the block runs, not when the macro expands, so the
default still follows redirect_stdout; the test's control asserts naming an io moves the
report rather than copying it.

1192 assertions, green.

🤖 Generated with Claude Code

…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>
@github-actions github-actions Bot added the enhancement New feature or request label Sep 8, 2026
@github-actions

github-actions Bot commented Sep 8, 2026

Copy link
Copy Markdown
Contributor

📚 Docs preview: https://codes.sota-shimozono.com/ExperimentalAPI.jl/previews/PR27/

(updates on each push to this PR)

@codecov

codecov Bot commented Sep 8, 2026

Copy link
Copy Markdown

Codecov Report

✅ All modified and coverable lines are covered by tests.

📢 Thoughts on this report? Let us know!

@sotashimozono
sotashimozono merged commit 8eb0b34 into main Sep 8, 2026
14 checks passed
@sotashimozono
sotashimozono deleted the feat/declare-the-young-layers branch September 8, 2026 12:58
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

enhancement New feature or request

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant