plans/2026-08-08-public-release.md

@@ -1,4 +1,4 @@
-# uscogdata 0.1.0 Public Release Implementation Plan
+# uscogdata 0.3.0 Public Release Implementation Plan
 
 > **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
 
@@ -511,6 +511,14 @@ Change:
 MaxCorpusSchema: 7
 ```
 
+Bump the version — this release changes user-visible behaviour (remote reads
+go from broken to working; the default URL from placeholder to live corpus),
+which is a minor bump, not a patch:
+
+```
+Version: 0.3.0
+```
+
 - [ ] **Step 4: Verify the person object parses**
 
 Run: `Rscript -e 'print(eval(parse(text = read.dcf("DESCRIPTION")[1, "Authors@R"])))'`
@@ -887,10 +895,21 @@ Before deleting anything, move each of these to its documentation home. Verify e
 
 Run `Rscript -e 'devtools::document()'` after editing roxygen.
 
-- [ ] **Step 2: Replace NEWS.md entirely**
+- [ ] **Step 2: Restructure NEWS.md**
+
+Three edits, in this order:
+
+1. **Prepend** the `0.3.0` section below.
+2. **Keep** the existing `# uscogdata 0.2.0` section verbatim — it is a real
+   changelog (`"All Categories"`, the coverage-signposting fix, the
+   `n_units_reporting` documentation) and users deserve it.
+3. **Delete** the entire `# uscogdata 0.1.0 (development)` section and
+   everything under it. That is pre-release churn; it stays in git.
+
+The new top section:
 
 ```markdown
-# uscogdata 0.1.0
+# uscogdata 0.3.0
 
 First public release.
 
@@ -939,7 +958,15 @@ provenance; `cog_mirror()` for a local copy.
 
 Run: `git show HEAD:NEWS.md > /tmp/news-old.md && wc -l /tmp/news-old.md NEWS.md`
 
-Read `/tmp/news-old.md` once more and confirm every substantive claim either appears in the new NEWS, landed somewhere in Step 1, or is genuinely pre-release churn (version bumps, fixture regenerations, internal refactors). The pre-release history stays in git; it does not need preserving in NEWS.
+Read `/tmp/news-old.md` once more and confirm every substantive claim from the **deleted `0.1.0 (development)` section** either appears in the new `0.3.0` section, landed somewhere in Step 1, or is genuinely pre-release churn (version bumps, fixture regenerations, internal refactors).
+
+Then confirm the `0.2.0` section survived intact:
+
+```bash
+diff <(git show HEAD:NEWS.md | sed -n '/^# uscogdata 0.2.0/,/^# uscogdata 0.1.0/p' | head -n -1) \
+     <(sed -n '/^# uscogdata 0.2.0/,$p' NEWS.md)
+```
+Expected: no output. Any diff means the `0.2.0` changelog was damaged — restore it.
 
 - [ ] **Step 4: Run the full suite**
 
@@ -950,7 +977,7 @@ Expected: PASS — `devtools::document()` in Step 1 regenerated `man/`, so this
 
 ```bash
 git add NEWS.md README.md R/ man/
-git commit -m "docs: rewrite NEWS as an initial release
+git commit -m "docs: recast NEWS around the first public release
 
 The changelog described changes relative to states no user ever saw, which
 reads as instability to someone deciding whether to depend on this. The
@@ -990,7 +1017,7 @@ It must contain, in this order:
    ```
    ````
    Explain why it exists: every other test path uses a local corpus, which is
-   how the remote-read defect in 0.1.0 went unnoticed.
+   how the remote-read defect fixed for 0.3.0 went unnoticed.
 
 5. **Do not exclude the fixture from the build.** State the reason — it is what lets `R CMD check` pass on r-universe and GitHub Actions with no credentials.
 
@@ -1061,4 +1088,4 @@ Run before declaring the release ready. Every one of these must pass.
 
 ## Out of scope for this plan
 
-Flipping the Gitea repo public, `gitleaks`, the GitHub mirror and its Actions matrix, the Gitea push workflow, the r-universe registry, and tagging `v0.1.0`. Those follow after this plan's final verification is green — r-universe publishes check results on registration, so registering before checks pass means a red badge on day one. Corrections intake and announcement posts are deferred by decision (see the spec).
+Flipping the Gitea repo public, `gitleaks`, the GitHub mirror and its Actions matrix, the Gitea push workflow, the r-universe registry, and tagging `v0.3.0`. Those follow after this plan's final verification is green — r-universe publishes check results on registration, so registering before checks pass means a red badge on day one. Corrections intake and announcement posts are deferred by decision (see the spec).

specs/2026-08-08-public-release-design.md

@@ -1,4 +1,4 @@
-# `uscogdata` 0.1.0 — public release
+# `uscogdata` 0.3.0 — public release
 
 **Date:** 2026-08-08 · **Status:** design, awaiting approval
 **Scope:** release-readiness, README, NEWS. Distribution mechanics recorded here as
@@ -176,15 +176,25 @@ with a URL that resolves for someone who has only this repo.
 
 ## NEWS.md
 
-The current NEWS is a pre-release churn log: changes described relative to states
+`NEWS.md` currently holds two sections. `0.2.0` is a legitimate changelog — the
-no user has seen ("Breaking: corpus schema_version 4", "the package now
+`"All Categories"` reserved value, the coverage-signposting fix, the
-requires…"), newest-first across the package's entire pre-release development
+`n_units_reporting` documentation — and it stays. Beneath it,
-(2026-04-23 to 2026-08-04, 140 commits). To a newcomer evaluating whether to
+`0.1.0 (development)` is a pre-release churn log: changes described relative to
-depend on the package, it reads as instability.
+states no user has ever seen ("Breaking: corpus schema_version 4", "the package
+now requires…"), spanning the package's entire pre-release development. To a
+newcomer deciding whether to depend on this, that section reads as instability.
 
-**0.1.0 is rewritten as an initial release**: what the package does, what the
+**A new `0.3.0` section is added at the top, framed as the first public
-corpus covers, and the caveats that are genuinely load-bearing. The pre-release
+release**: what the package does, what the corpus covers, and the caveats that
-history is not preserved in NEWS — it is in git, where it belongs.
+are genuinely load-bearing. **`0.2.0` is kept verbatim.** **`0.1.0 (development)`
+is dropped** — that history stays in git, where it belongs.
+
+The version is `0.3.0` rather than `0.2.0` because this release changes
+user-visible behaviour: remote corpus reads go from broken to working, and the
+default URL from a dead placeholder to a live corpus. It is also not `1.0.0` —
+the corpus still excludes government types 4 and 5 pending validation, so a
+stability promise would overclaim. No git tag exists for any prior version;
+`chore: release 0.2.0` bumped `DESCRIPTION` and `NEWS` only.
 
 The substantive content is migrated, not deleted. These are hard-won and belong
 in documentation rather than buried in a changelog:
@@ -224,7 +234,7 @@ which is a worse first impression than a week's delay.
    account — r-universe links maintainer identity by matching DESCRIPTION's email
    against registered GitHub emails, and the association only takes effect on the
    next build.
-6. Tag `v0.1.0`. Create `github.com/civilytics/civilytics.r-universe.dev` with a
+6. Tag `v0.3.0`. Create `github.com/civilytics/civilytics.r-universe.dev` with a
    `packages.json` pinned to the tag, pointing at the GitHub mirror rather than
    Gitea so clone traffic stays off maxwell. Install the r-universe app.