docs: retarget the release at 0.3.0 and preserve the 0.2.0 changelog
Spec and plan were written against a branch 25 commits behind main, where the package still read 0.1.0. It is 0.2.0, with a real 0.2.0 changelog in NEWS that the plan would have deleted. 0.3.0 rather than 0.2.0 because remote corpus reads go from broken to working and the default URL from placeholder to live -- user-visible behaviour, so a minor bump. Not 1.0.0: types 4 and 5 remain out of scope. Task 9 now prepends a 0.3.0 section, keeps 0.2.0 verbatim with a diff check to prove it, and drops only the 0.1.0 development churn. Task 4 gains the Version bump.
This commit is contained in:
@@ -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).
|
||||
|
||||
@@ -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
|
||||
no user has seen ("Breaking: corpus schema_version 4", "the package now
|
||||
requires…"), newest-first across the package's entire pre-release development
|
||||
(2026-04-23 to 2026-08-04, 140 commits). To a newcomer evaluating whether to
|
||||
depend on the package, it reads as instability.
|
||||
`NEWS.md` currently holds two sections. `0.2.0` is a legitimate changelog — the
|
||||
`"All Categories"` reserved value, the coverage-signposting fix, the
|
||||
`n_units_reporting` documentation — and it stays. Beneath it,
|
||||
`0.1.0 (development)` is a pre-release churn log: changes described relative to
|
||||
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
|
||||
corpus covers, and the caveats that are genuinely load-bearing. The pre-release
|
||||
history is not preserved in NEWS — it is in git, where it belongs.
|
||||
**A new `0.3.0` section is added at the top, framed as the first public
|
||||
release**: what the package does, what the corpus covers, and the caveats that
|
||||
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.
|
||||
|
||||
|
||||
Reference in New Issue
Block a user