Skip to content

Automate the quarterly APC/APNI release - #316

Open
wcornwell wants to merge 3 commits into
masterfrom
apc-release-workflow
Open

wcornwell wants to merge 3 commits into
masterfrom
apc-release-workflow

Conversation

@wcornwell

Copy link
Copy Markdown
Contributor

Adds an apc-release workflow that downloads the NSL exports quarterly, checks them against the latest release, and creates a dated release: published if the checks pass, a draft (and a failed run) if they need review, nothing if unchanged or broken.

The checks live in R/release.R, with tests in test-release.R. Details in the first comment.

Part of #315.

🤖 Generated with Claude Code

Add an apc-release workflow that downloads the NSL exports, checks
them against the latest release (columns, key columns, APC row drop,
a smoke-test alignment) and creates a dated release: published if the
checks pass, a draft if they need review, nothing if unchanged.

Part of #315.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@wcornwell

Copy link
Copy Markdown
Contributor Author

Details

What it does (the decisions on #315: publish automatically, run quarterly, a ~2% drop flags manual review)

Outcome When Result
fail a table has no rows; columns differ from the previous release (names or types); a key column is entirely empty; the smoke test fails no release, and the run fails
review APC lost more than 2% of its rows; a key column has some missing values a draft release whose notes list the problems, and the run fails so someone is notified
unchanged same row counts and latest modified time as the previous release no release
pass otherwise published (scheduled runs, or manual runs with publish ticked); otherwise a draft

Draft releases are invisible to default_version(), which reads the public releases list without authentication, so users never get a draft by default.

  • Smoke test: the new files are loaded through the normal load_taxonomic_resources() path (R_USER_DATA_DIR points tools::R_user_dir() at a temporary copy), then 8 names are run through create_taxonomic_update_lookup(), one of them deliberately misspelt. All 8 give the same accepted names in both 2024-10-11 and 2026-11-15.
  • Tag: today's date in Sydney. If a release or draft with that tag already exists, the run stops.
  • Schedule: 0 0 1 1,4,7,10 *, i.e. the morning of the 1st of Jan, Apr, Jul and Oct in Sydney.
  • Download: retried 3 times, 2 minutes apart. The job times out after 60 minutes.
  • Permissions: only contents: write with the built-in GITHUB_TOKEN. No new secrets.
  • Run summary: each run writes a before/after table (rows and latest modified) to its summary page.
  • Small cleanup: download_taxonomic_resources_for_release() loses its unused version_name argument and now returns the release summary.

Testing

  • test-release.R passes (24 expectations): each outcome with small synthetic tables, a parquet round trip, and the smoke test on the 2024-10-11 files, including a doctored APC without Eucalyptus regnans. I haven't run the full suite or R CMD check locally; CI covers those.
  • Ran .github/scripts/apc-release.R locally against live NSL:
    • Against 2026-11-15: pass. Same row counts (APC 114,021; APNI not in APC 22,979), but the latest modified time moved from 2026-11-13 to 2026-11-17.
    • A second run against those new files: unchanged, so no release.

After merging

  • GitHub only allows a manual run once the workflow file is on master. So step 5 of Automate APC/APNI download and GitHub release #315 (a manual run, compared against 2026-11-15) has to happen after merging. A manual run creates a draft unless publish is ticked, so this is safe.
  • GitHub turns off scheduled workflows in a public repo after 60 days with no activity. With a quarterly schedule, a quiet patch could switch it off; the Actions tab would show it as disabled.

Open for @ehwenk: does a missing value in a key column belong in "review" (as now) or "fail"?

@wcornwell
wcornwell requested a review from dfalster November 18, 2026 03:44
wcornwell and others added 2 commits November 18, 2026 15:17
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
- The smoke test failed open: if the release files couldn't be loaded,
  it reported no problems. It now fails, and it also checks two
  APNI-only names, the aligned name and the taxonomic status.
- APNI losing more than 10% of its rows, or more duplicated APC
  taxonIDs, now needs review. Previously APNI cut to 10% passed.
- Missing values count only when they increase, and "unchanged" is
  checked before "review", so a problem already in the published
  release no longer gives a new draft every quarter.
- The workflow runs monthly and re-enables itself through the API,
  because GitHub disables scheduled workflows after 60 days without
  repository activity. It still releases only in Jan, Apr, Jul and Oct.

Part of #315.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@dfalster

Copy link
Copy Markdown
Member

Pushed 4aa47ff with fixes from a review. I tested each one against the four cached releases (2024-10-11, 2026-03-25, 2026-07-30, 2026-11-15). The checks still return "pass" on all three past transitions.

The smoke test passed when it couldn't load the release files. If load_taxonomic_resources() returns NULL, create_taxonomic_update_lookup() returns NULL as well, so no name was counted as wrong. Running check_release_alignment() on an empty directory gave character(0). It now reports a problem in that case, and also when the files can't be copied.

The smoke test now also checks two names found only in APNI, Hakea paludosa and Viola linifolia. They give the same result in 2024-10-11 and 2026-11-15. For every name it now compares the aligned name, the accepted name and the status, not only the accepted name.

There was no check on APNI's size. With APNI cut to 10% of its rows, or APC doubled, the result was "pass". These now need review:

  • APNI losing more than 10% of its rows. It normally shrinks by 1.4–5.3% between releases, as names move into APC.
  • More duplicated APC taxonID values than in the previous release.

A problem that persisted would have created a draft every quarter. "review" was checked before "unchanged", and the draft never becomes the previous release. Missing values in key columns now count only when there are more than in the previous release, and "unchanged" is checked first. This also answers the open question about missing values: they stay as "review", but are measured against the previous release.

The schedule is now monthly, with a step that keeps it enabled. GitHub disables scheduled workflows in a public repo after 60 days without repository activity, and the workflow's own runs don't count, so a quarterly schedule would be switched off by any quiet quarter.

  • There are now two cron lines. The quarterly one runs the release job. The other months run only a keepalive job, which calls PUT /actions/workflows/apc-release.yaml/enable.
  • Permissions are now set per job: contents: write for release, actions: write for keepalive.
  • One assumption I couldn't confirm in GitHub's docs: that enabling an already-enabled workflow resets the 60-day clock. This is the method community keepalive actions use. It would be worth checking the Actions tab once after a quiet stretch.

Not changed, for you to decide:

  • A new NSL column still counts as "fail". The loader handles extra columns fine (it uses rename(any_of()) and select()), so "review" might fit better.
  • Nothing saves release/ as a workflow artifact when a run fails, so a failed run leaves no files to inspect.
  • readr::problems() isn't checked, so if NSL changes a logical or date column, the values become NA with only a warning.

Tests: test-release.R has 35 passing expectations. The full suite passes locally (457).

This branch has not been deployed

No deployments
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.

2 participants