From be3097da2074dac3f28b714ea9370fe057112f24 Mon Sep 17 00:00:00 2001 From: "Joshua Uhalt, Ph.D." Date: Mon, 28 Sep 2026 13:51:31 -0400 Subject: [PATCH] Document the handoff to nomologR on the README, and fix the RC-day order The maintainer asked that each package's README document the handoff in its own section near the bottom. "The handoff to nomologR", just above References, says what a handoff carries, how to make one (with the README's own fit), the two nomologR calls that read it, how to read its decisions (the reader contract in ?content_handoff), and how schema 1 is versioned. nomologR's README carries the mirror section, "The handoff from contentvalidR", with the same reader-contract wording. ROADMAP.md now gives the release-candidate day in the order agreed with nomologR, so that nomologR's tests pass before either package tags: the 0.99.0 commit and its fixtures first, then nomologR's suite, then both tags, contentvalidR's on exactly the commit the fixtures came from. Opens the 0.10.0.9000 development version. Co-Authored-By: Claude Opus 5.5 --- DESCRIPTION | 2 +- NEWS.md | 8 ++++++++ README.Rmd | 26 ++++++++++++++++++++++++++ README.md | 51 +++++++++++++++++++++++++++++++++++++++++++++++++++ ROADMAP.md | 15 +++++++++++---- 5 files changed, 97 insertions(+), 5 deletions(-) diff --git a/DESCRIPTION b/DESCRIPTION index c6dd0e8..8d32b55 100644 --- a/DESCRIPTION +++ b/DESCRIPTION @@ -1,7 +1,7 @@ Package: contentvalidR Type: Package Title: Tools for Substantive and Content Validity Pretesting -Version: 0.10.0 +Version: 0.10.0.9000 Authors@R: c( person(given = "Joshua", family = "Uhalt", email = "Josh.Uhalt@gmail.com", role = c("aut", "cre")) diff --git a/NEWS.md b/NEWS.md index 1c7d523..78a88a1 100644 --- a/NEWS.md +++ b/NEWS.md @@ -1,3 +1,11 @@ +# contentvalidR 0.10.0.9000 (development version) + +* The README has a section on the handoff to nomologR, just above the + references: what a handoff carries, the two nomologR calls that read it, how + to read its decisions, and how the schema is versioned. The nomologR README + carries the mirror section, so the handoff can be found from either + package's front page. + # contentvalidR 0.10.0 Tenth public release, and the last planned before the joint 1.0 release diff --git a/README.Rmd b/README.Rmd index 6590f7e..4bae7b2 100644 --- a/README.Rmd +++ b/README.Rmd @@ -144,6 +144,32 @@ Five deterministic example data sets, covering the item-sort, construct-rating, Cite the package with `citation("contentvalidR")`. The reference list below is also installed in BibTeX form: `system.file("REFERENCES.bib", package = "contentvalidR")`. +## The handoff to nomologR + +Content review decides which items go on to be tested with response data. `content_handoff()` packages that decision so the empirical stage can pick it up without retyping anything, and [nomologR](https://github.com/JUhalt/nomologR) is the partner package that reads it. A handoff carries: + +- the items carried forward, and the items held back, each with its status, its recommendation, and the rule that made the decision; +- the scales, where the design maps items to constructs; +- each item's statistics, with their intervals and criteria, and the panel's agreement where one was computed; +- two facts about the instrument that only you know: which items are reverse-worded (`reverse_keyed`, or `character(0)` if you checked and none is) and the response scale respondents will answer on (`response_scale`). + +```{r handoff} +h <- content_handoff(fit, reverse_keyed = character(0), response_scale = c(1, 5)) +h$items +``` + +Once responses are collected, pass the handoff itself to nomologR, not `h$items`, so the keying and the reasons for anything held back travel with the items: + +```{r handoff-nomologr, eval=FALSE} +library(nomologR) +nomo_screen(responses, items = h) # screens the carried items +nomo_run(responses, scales = h) # runs the empirical stage on the handoff's scales +``` + +**Reading a handoff.** Take each item's decision from `carried` and `status`; never re-derive it by comparing a statistic with its criterion, or by branching on the version that produced it. `recommendation` states the same decision in the workflow's own words and, like `rule`, is prose. A `keying` of `NA` means nobody said, never that an item is forward-worded. + +**Versions.** The handoff is schema version 1, frozen since 0.7.0: its fields and columns keep their names, positions, and types, and new optional ones may only be added at the end. A change that broke this would be schema version 2, produced beside version 1 for at least a release cycle. The reader in nomologR is tested against handoffs from contentvalidR 0.6.0 through 0.9.0, and neither package depends on the other. See `?content_handoff` for the full contract, `vignette("handoff-to-empirical-validation")` for a guide, and `vignette("one-item-set-both-stages")` for the joint walkthrough. + ## References Works cited in this README, the help pages, and the vignettes. diff --git a/README.md b/README.md index c46cdf5..ca52eb1 100644 --- a/README.md +++ b/README.md @@ -267,6 +267,57 @@ Cite the package with `citation("contentvalidR")`. The reference list below is also installed in BibTeX form: `system.file("REFERENCES.bib", package = "contentvalidR")`. +## The handoff to nomologR + +Content review decides which items go on to be tested with response +data. `content_handoff()` packages that decision so the empirical stage +can pick it up without retyping anything, and +[nomologR](https://github.com/JUhalt/nomologR) is the partner package +that reads it. A handoff carries: + +- the items carried forward, and the items held back, each with its + status, its recommendation, and the rule that made the decision; +- the scales, where the design maps items to constructs; +- each item’s statistics, with their intervals and criteria, and the + panel’s agreement where one was computed; +- two facts about the instrument that only you know: which items are + reverse-worded (`reverse_keyed`, or `character(0)` if you checked and + none is) and the response scale respondents will answer on + (`response_scale`). + +``` r +h <- content_handoff(fit, reverse_keyed = character(0), response_scale = c(1, 5)) +h$items +#> [1] "Clear 1" "Clear 2" +``` + +Once responses are collected, pass the handoff itself to nomologR, not +`h$items`, so the keying and the reasons for anything held back travel +with the items: + +``` r +library(nomologR) +nomo_screen(responses, items = h) # screens the carried items +nomo_run(responses, scales = h) # runs the empirical stage on the handoff's scales +``` + +**Reading a handoff.** Take each item’s decision from `carried` and +`status`; never re-derive it by comparing a statistic with its +criterion, or by branching on the version that produced it. +`recommendation` states the same decision in the workflow’s own words +and, like `rule`, is prose. A `keying` of `NA` means nobody said, never +that an item is forward-worded. + +**Versions.** The handoff is schema version 1, frozen since 0.7.0: its +fields and columns keep their names, positions, and types, and new +optional ones may only be added at the end. A change that broke this +would be schema version 2, produced beside version 1 for at least a +release cycle. The reader in nomologR is tested against handoffs from +contentvalidR 0.6.0 through 0.9.0, and neither package depends on the +other. See `?content_handoff` for the full contract, +`vignette("handoff-to-empirical-validation")` for a guide, and +`vignette("one-item-set-both-stages")` for the joint walkthrough. + ## References Works cited in this README, the help pages, and the vignettes. diff --git a/ROADMAP.md b/ROADMAP.md index b6fe70b..208ff07 100644 --- a/ROADMAP.md +++ b/ROADMAP.md @@ -860,10 +860,17 @@ reads no handoffs and takes no part in the joint 1.0. another round is needed). It is a tag only, never a GitHub release, because R-universe publishes GitHub releases to users. Handoff fixtures from a candidate are named `handoff--v0.99.0.rds`. - - **2026-10-17, release-candidate day.** `agreement_summary()` is removed, - the version becomes 0.99.0, and `v1.0.0-rc.1` is tagged. Then the round - below runs: the fixture set goes to nomologR, and the compatibility - table, the shared handoff example, and the release notes are drafted. + - **2026-10-17, release-candidate day,** for both packages, in this order, + agreed with nomologR so that its tests pass before either package tags: + 1. contentvalidR removes `agreement_summary()`, sets the version to + 0.99.0, pushes that commit untagged, and generates the fixture set + from it, with the commit recorded in the manifest; + 2. nomologR adds the fixtures, reads 0.99.0 as a producer version, and + runs its suite; + 3. once that passes, both packages tag `v1.0.0-rc.1`, contentvalidR on + exactly the commit the fixtures came from; + 4. then the compatibility table, the shared handoff example, and the + release notes are drafted. - **CRAN submission, after that.** CRAN asks for updates to an established package no more often than every one to two months. So the joint 1.0 goes to CRAN no sooner than about a month after the later of the two