Skip to content

Settle the last help pages, tests and gate stage before the 1.0 freeze - #103

Merged
JUhalt merged 7 commits into
masterfrom
fix/pre-freeze
Nov 16, 2026
Merged

JUhalt merged 7 commits into
masterfrom
fix/pre-freeze

Conversation

@JUhalt

@JUhalt JUhalt commented Nov 16, 2026

Copy link
Copy Markdown
Owner

The last changes before the release candidate. The tag v1.0.0-rc.1 freezes the code, the help pages, the vignettes and the tests until 1.0.0; a readiness check of the whole release found a few things that had to go in first or wait until after 1.0. The maintainer chose to put them in.

No computed value and no returned field changes, and a handoff carries what it carried before.

What changes

  • The stability policy gives one answer on removal. ?contentvalidR said an auxiliary (Tier 3) helper such as qfactor_content() could be removed after one minor release of warning, and also that from 1.0 onward nothing is removed except in a major release. At 1.0.0 that page becomes the promise, so it now says once: from 1.0 onward a Tier 1 or Tier 2 function, argument, or returned field is removed only in a major release; a Tier 3 helper, or an argument or returned field of one, may be removed in a minor release after its one minor release of warning. The README sentence matches.
  • The workflow and mode values of a handoff are frozen and listed. ?content_handoff told a reader to match on the workflow in provenance and never said what the values are. It now lists them under "What version 1 freezes": workflow is "item-sort", "construct-rating", "expert-panel", or "delphi"; mode is "relevance", "essentiality", "congruence", or NA. A new workflow or mode would add a value; none is renamed. The values are the ones the package already writes, and nomologR, which prints both and matches on neither, has no objection.
  • One table of where each interval's bounds are. The lower and upper bound of an interval have six pairs of column names across the package's results (psa_low/psa_high, ci_low/ci_high, I_CVI_low/I_CVI_high, agreement_low/agreement_high, stability_low/stability_high, lower/upper), each documented only on its own page. ?"contentvalid-data-frames" and vignette("reading-output") now list all fourteen places in one table and say where each result records the confidence level and the method. Nothing is renamed; the page says the names are stable.
  • Tests that used to run nowhere but by hand.
    • The frozen-schema test now covers construct-rating and congruence handoffs (with a target mapping, without one, and one that carries no item), which it did not, although congruence is the handoff the audit changed most. All four match the schema.
    • Nineteen tests skipped under R CMD check and in CI because they looked for the source tree. Fourteen now read the installed copies of the help pages and vignettes there (tests/testthat/helper-sources.R), and still read the sources when run from the source tree. The five that need README.Rmd or the R/ sources, which are not installed, still skip there.
  • The release gate has a fourth stage, tests (tools/, not shipped). It runs second, after build: the whole suite from the source tree the tarball was built from, failing on a failure, an error, or a test that skips for want of the sources or documentation, which cannot be true in a source tree. So the five source-only tests, and the source copies of the help pages and vignettes, are tested at every gate, not only when someone remembers.
  • cran-comments.md names one more change that stops code which ran under 0.4.0: aikens_v() now requires lo and hi.

How it was made and checked

  • Work: three areas (help pages, tests, gate), each implemented in its own working copy and then reviewed by a second, read-only reviewer who ran the code. The reviews raised 15 points, none blocking. Twelve are fixed here. Three stand as they are: the new table is about 85 columns wide in text help, as two other pages already are (HTML is unaffected); the table keeps its row for delphi_validity()$details$stability, since details is part of the documented object; and the test of where the level and method are recorded checks that each place named exists, not that no other is named.
  • Tests: 5514 pass, 0 fail, 0 skipped, from the source tree; spelling clean.
  • Installed package: the work was built, installed into a fresh library and tested from a copy of tests/ outside any source tree, as R CMD check does: 0 failures and the 5 expected skips. That run came before the review fixes; the gate's check stage below ran the suite against the installed package again, with no failure.
  • Release gate: passed on 756e440, the head of this pull request, with all four stages: build; tests (5514 passed, 0 skipped, from the source tree); smoke (withr the one declared dependency added); and R CMD check --as-cran (0 errors, 0 warnings, the 2 expected notes).

For nomologR

Nothing a handoff carries changes: no field, column, value, statistic name or decision word. The dry run nomologR passed against 768d606 (the same tree as master before this pull request) still describes the producer.

🤖 Generated with Claude Code

JUhalt and others added 7 commits October 9, 2026 20:17
test-handoff-schema.R said it checked a handoff from every workflow that
can hand off, and built five. It now also builds a construct-rating
handoff and three item-objective congruence handoffs from the package's
example data: one with a target mapping, one without that carries its
"Descriptive only" items, and the same fit with the default `keep`,
which carries no item. Each is compared with .handoff_schema() like the
rest, and a new test pins the two edge cases so they cannot go missing
if the example data changes.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Nineteen tests looked for the source tree and skipped without it, so
they never ran under R CMD check or in CI. Fourteen now fall back to
what an installed package carries: eight read a help page through
tools::Rd_db(), and six read a vignette's source from doc/. The lookups
are in one helper, tests/testthat/helper-sources.R, and no assertion
changed.

From the source tree every test still reads the source, and a help page
missing from man/ is now an error there instead of a skip. Five tests
read README.Rmd or the R/ sources, which are not installed, and still
skip with their reason unchanged; two of them check the vignettes first.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
The stability policy (?contentvalidR) gave two rules for removal after
1.0: the Tier 3 paragraph allowed a minor release, and step 3 of the
deprecation cycle required a major one. Step 3 now states the rule once.
From 1.0 onward a Tier 1 or Tier 2 function, argument, or returned field
is removed only in a major release; a Tier 3 helper is the exception and
may be removed in a minor release, after its one minor release of
warning. The Tier 3 paragraph points to that step.

?content_handoff told a reader to match on the workflow in provenance
without giving the values. "What version 1 freezes" now lists them:
workflow is "item-sort", "construct-rating", "expert-panel", or "delphi";
mode is "relevance", "essentiality", or "congruence", and NA outside an
expert panel. They are frozen for schema version 1: a new workflow or
mode would add a value, and none is renamed.

Interval bounds have six pairs of names across the results, each
documented only on its own page. ?"contentvalid-data-frames" gains a
section, "Interval columns", with one table of which result holds which
pair, and where the confidence level and the method are recorded. The
names are stable and none is renamed. vignette("reading-output") carries
the same table. Nothing is renamed and no value changes.

tests/testthat/test-prefreeze-docs.R parses the three pages and checks
each claim against real results, so it fails if the policy loses the
exception or gains a second rule, if a workflow or mode value is missing
from the handoff page or listed without being written, or if the table
names a column its result does not have. It reads the installed help
when the source tree is absent, as under R CMD check.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
R CMD check and CI test the installed package, where the tests that read
the source tree skip: 19 of them at 0.10.1.9000, 11 for want of the
sources and 8 for want of man/. Those tests ran only when someone
remembered to run devtools::test() by hand before a release.

The gate now has four stages: build, tests, smoke, check. The tests stage
runs devtools::test() on the source tree in its own process. It fails on
a failed expectation, on an error, and on a skip whose reason is that the
package sources or documentation are not available, which cannot be true
in a source tree. Any other skip is listed and does not fail it. It
prints one line of counts and every skip with its file and reason.

It runs second. It needs what build leaves: the regenerated man/, and the
stamp of the tree the tarball was built from, which it checks before it
runs, as smoke and check do. It takes the stamp again afterwards, so a
test that writes into the tree fails here rather than at smoke. And it
fails in minutes, before the long check stage.

A run of build, smoke and check is now a partial run, and the closing
message says that only a run of all four stages is the gate.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Help pages: a handoff states the interval level and method beside each
interval, with NA where there is none, not "in every row"; the interval
section no longer says when each name was chosen, and notes that
content_report() writes an interval as text; the Tier 3 exception in the
stability policy covers an argument or returned field of a helper too.
The README states the same rule.

Tests: the new help-page test skips, not errors, when the installed help
cannot be read; the Scheibe reference test reads the installed files
first, so two of its checks also run under R CMD check; the ASCII test
skips where the R directory holds no source file; the schema test
builds its handoffs once.

Release gate: the tests stage takes its skips from the reporter, so a
skip at the top of a file is counted and can fail the stage; it runs
inside local() so the tests see a clean global environment; its
messages and the README say what the stamp watches, and that NOT_CRAN is
set only when unset. The README gives the number of source-only tests as
it is now, five.

NEWS gains "Settled before the release candidate", and cran-comments.md
names aikens_v() requiring lo and hi.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@JUhalt
JUhalt merged commit 61dc4e9 into master Nov 16, 2026
8 checks passed
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.

1 participant