wsga-version-bump

name

wsga-version-bump

description

Bump the wsga package version across all 11 version-bearing files (R `DESCRIPTION`, `NEWS.md`, the four Stata `.sthlp` files, both `.ado` files, both `.pkg` files, and `stata.toc`). Use BEFORE opening a PR that changes the R or Stata package in `acarril/wsga`. Trigger on phrases like "bump the version", "prepare a release", "release X.Y.Z", "version bump for wsga", or when a package-changing feature/bugfix branch is ready to merge and CLAUDE.md's versioning rule applies. Also use when correcting a prior bump (re-target the new version, run again). Do not skip — the R and Stata components share one unified version and any drift indicates this skill was bypassed.

wsga Version Bump

The wsga package is dual-language (R + Stata) and ships a unified MAJOR.MINOR.PATCH version. Eleven files carry the version string; any PR that changes the R or Stata package must bump all of them so the two never drift. (PRs touching only non-package files — e.g. docs/, specs/, CI workflows — do not need a bump.) This skill walks through the procedure end-to-end and verifies the result.

When to use

• Before opening a PR that changes the R or Stata package in acarril/wsga (CLAUDE.md mandates this).
• When the user says "bump the version", "prepare a release", "release 1.x.y".
• When a prior bump was wrong and needs correcting — re-run with the corrected target version. The procedure is idempotent if every location currently shows the same (wrong) version.

When NOT to use

• During the feature work itself. Bump only when the feature is committed and the branch is ready for review.
• On main. Bump on a feature/bugfix/chore branch.

Step 1 — Pre-flight

1. Confirm the working directory is the wsga git repo (typically /Users/acarril/Sidequests/rddsga/rddsga-repo). git rev-parse --show-toplevel should resolve there.
2. Confirm we're on a non-main branch: git branch --show-current. If on main, stop and ask.
3. git status --short — note any unstaged changes. The bump is cleanest when the feature work is already committed and the staging area is empty.

Step 2 — Determine bump type

Read the current version:

grep ^Version: DESCRIPTION

Ask the user which bump type to apply, with a one-line recommendation:

• patch (X.Y.Z → X.Y.Z+1) — bug fixes, internal refactors, doc-only changes, or maintainer-classified small additions.
• minor (X.Y.Z → X.(Y+1).0) — new public arguments/options, new exported functions, new public Stata options.
• major (X.Y.Z → (X+1).0.0) — breaking changes to the public API.

The maintainer (Alvaro) makes the final call. If they classify a new feature as patch, accept it without arguing — semver is a guideline, not a contract here.

Set NEW_VERSION (e.g., 1.0.3).

Step 3 — Today's date

Use today's date from your harness context (look for the currentDate line in the user's CLAUDE.md / system reminder). Format in two ways:

• YYYY-MM-DD — used everywhere except .pkg files
• YYYYMMDD — used only in the d Distribution-Date: line of .pkg files

Step 4 — The 11 locations

Apply Edit-tool substitutions in this order. Each line below shows the literal old-string → new-string pattern. Find the unique line in each file and replace it.

#	File	Replace
1	DESCRIPTION	Version: <old> → Version: <NEW>
2	NEWS.md	prepend a new ## wsga <NEW> (<YYYY-MM-DD>) section after the top heading (see Step 5)
3	stata/wsga.ado line 1	*! <old> Alvaro Carril <old-date> → *! <NEW> Alvaro Carril <YYYY-MM-DD>
4	stata/rddsga.ado line 1	same pattern
5	stata/wsga.sthlp line 2	{* *! version <old> <old-date>}{...} → {* *! version <NEW> <YYYY-MM-DD>}{...}
6	stata/wsga_rdd.sthlp line 2	same
7	stata/wsga_did.sthlp line 2	same
8	stata/rddsga.sthlp line 2	same
9	stata/wsga.pkg	v <old> → v <NEW> AND d Distribution-Date: <old-compact> → d Distribution-Date: <YYYYMMDD>
10	stata/rddsga.pkg	same pattern as #9
11	stata/stata.toc	v <old> → v <NEW>

Never touch

The procedure deliberately skips:

• The version 11.1 lines inside .ado files — that's the minimum Stata version, not the package version. The two share the same word ("version") but are unrelated.
• RoxygenNote: in DESCRIPTION — auto-generated by roxygen2::roxygenize(). Leave it alone.

Step 5 — NEWS.md entry

Prepend a section immediately after the # wsga (R package) NEWS heading. Format:

## wsga X.Y.Z (YYYY-MM-DD)

### <Subsection>

- Bullet describing change 1.
- Bullet describing change 2.

---

Pick the subsection that fits the bump's character:

• ### New features — minor/major with new public API
• ### Bug fixes — patches that fix incorrect behavior
• ### Documentation — doc-only changes
• ### Internal — refactors with no user-visible change

To draft the bullets, run:

git log main..HEAD --oneline

and translate each commit into a bullet. The maintainer can edit afterward. Reference issue/PR numbers in parentheses where applicable (e.g., (#30)).

If the bump also resolves pre-existing version drift in any of the 11 files (e.g., .pkg and .toc had different versions before the bump), call that out in the notes — it's the kind of thing the maintainer wants surfaced.

Step 6 — Verify

Run this batch — every location should show the new version, every date should be today:

echo "=== DESCRIPTION ===" && grep -n "^Version:" DESCRIPTION
echo "=== NEWS.md ===" && head -3 NEWS.md
echo "=== wsga.ado ===" && sed -n '1p' stata/wsga.ado
echo "=== rddsga.ado ===" && sed -n '1p' stata/rddsga.ado
echo "=== wsga.sthlp ===" && sed -n '2p' stata/wsga.sthlp
echo "=== wsga_rdd.sthlp ===" && sed -n '2p' stata/wsga_rdd.sthlp
echo "=== wsga_did.sthlp ===" && sed -n '2p' stata/wsga_did.sthlp
echo "=== rddsga.sthlp ===" && sed -n '2p' stata/rddsga.sthlp
echo "=== wsga.pkg ===" && grep -n "^v \|Distribution-Date" stata/wsga.pkg
echo "=== rddsga.pkg ===" && grep -n "^v \|Distribution-Date" stata/rddsga.pkg
echo "=== stata.toc ===" && sed -n '1p' stata/stata.toc

If anything still shows the old version or a stale date, fix it and re-verify before staging.

Step 7 — Stage

git add DESCRIPTION NEWS.md \
        stata/wsga.ado stata/rddsga.ado \
        stata/wsga.sthlp stata/wsga_rdd.sthlp stata/wsga_did.sthlp stata/rddsga.sthlp \
        stata/wsga.pkg stata/rddsga.pkg stata/stata.toc

Do not commit unless the user explicitly asks. The harness's git-safety rules require asking before committing. The standard commit message for this work is:

chore(release): bump version to X.Y.Z

<one-line rationale, e.g., "Adds the wild cluster bootstrap option for
R and Stata DiD; see preceding commit and NEWS.md.">

Step 8 — Post-merge: tag and release on GitHub

After the PR merges to main, create a GitHub release for the new version. Every version bump corresponds to a release — see the rationale in the repo's release strategy (R users can pin via devtools::install_github("acarril/wsga@vX.Y.Z"); methods papers citing the package need stable references).

Triggered when the user (or you) confirms the merge has landed. Run from main after a git pull:

# Extract this version's NEWS section into a temp file
awk -v v="X.Y.Z" '
  $0 ~ "^## wsga " v " " { in_section = 1; next }
  /^---$/ && in_section { exit }
  in_section { print }
' NEWS.md > /tmp/wsga_release_notes.md

# Tag the merge commit (we are on main, so HEAD is the merge commit)
git tag -a vX.Y.Z -m "wsga X.Y.Z"
git push origin vX.Y.Z

# Create the GH release
gh release create vX.Y.Z --repo acarril/wsga \
  --title "wsga X.Y.Z" \
  --notes-file /tmp/wsga_release_notes.md

If you're backfilling releases for past version bumps (because the tag/release was missed earlier), tag at the merge commit of the PR that introduced that version. Find it via:

git log --first-parent main --oneline | grep "Merge pull request #<N>"

and pass the SHA as a positional argument to git tag -a vX.Y.Z <sha> -m "...". The release is non-blocking — if the user wants to do it themselves through the GitHub UI, the tag+push is enough; they can gh release create later.

Notes for the next maintainer

• The version drift problem is real: in practice, the .pkg files and stata.toc have repeatedly fallen out of sync with DESCRIPTION. If you encounter drift mid-bump, target everything at the same new version and mention the drift in NEWS.md so the resolution is logged.
• If a Stata file is added to the package later, this skill needs an update — the count of locations is not fixed by nature; it's fixed by the current file inventory.