@futurelastic/colab-handbook 1.13.0-rc.20 → 1.13.0-rc.21

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/package.json CHANGED
@@ -33,5 +33,5 @@
33
33
  "engines": {
34
34
  "node": ">=18"
35
35
  },
36
- "version": "1.13.0-rc.20"
36
+ "version": "1.13.0-rc.21"
37
37
  }
@@ -20,6 +20,9 @@
20
20
  # hand-off where
21
21
  # the final is a
22
22
  # human's)
23
+ # an hourly schedule (#547) — the cut colab release cut --auto, only when main's head
24
+ # only, never promote or finalize has no tag AND the fetched CLI moved in the last
25
+ # RETRY_WINDOW_MINUTES (or a run here was displaced)
23
26
  # workflow_dispatch all three, in that order
24
27
  # any of the above tagged something, and npm publish (job `npm`, #433) — candidates to
25
28
  # project.yml declares release.npm dist-tag `next`, finals to `latest`; see the
@@ -115,6 +118,23 @@
115
118
  # pre-releases, never "Latest". The audit's pre-release deploy-trigger check (#332) still
116
119
  # applies to your deploy workflows exactly as before.
117
120
  #
121
+ # A REFUSAL THE HANDBOOK FIXES IS RETRIED WITHIN THE HOUR (#547). A cut can be refused by a defect in
122
+ # the colab CLI rather than in your repo — a false positive in one of its checks. The fix reaches you
123
+ # when HANDBOOK_REF's channel moves, and nothing in your repo changes, so neither trigger above fires:
124
+ # the candidate would wait for your next merge or the next daily run (measured: ~2.5 h until a person
125
+ # dispatched it by hand, ~22 h otherwise). So an hourly run re-tries the CUT, and only the cut, when:
126
+ # - main's head carries no release tag yet (a head that has one has nothing to retry), and
127
+ # - the CLI this run fetched reached HANDBOOK_REF within RETRY_WINDOW_MINUTES — read from the date of
128
+ # the release tag at that commit (when the channel moved onto it), else the commit's own date; or
129
+ # - the newest other run of this workflow at main's head was cancelled. An hourly run shares the
130
+ # `release-auto` concurrency group, and GitHub cancels a PENDING run in a group when a newer one
131
+ # queues — so an hourly run can displace the very run a merge started. It then does that run's cut.
132
+ # Every other hourly run checks those and stops: no cut, no promotion, no finalize, so a held head is
133
+ # not tagged sooner than the daily run would tag it, and a standing refusal is not re-announced every
134
+ # hour. Nothing is stored between runs; the facts are re-read each time. EDIT: the cron string inside
135
+ # RETRY_RUN (release job env) must stay byte-identical to the hourly `cron:` line, or no run is
136
+ # recognised as a retry run — and the hourly run would then promote and finalize every hour.
137
+ #
118
138
  # A REFUSAL IS NOT A FAILURE. `colab release cut --auto` refusing (nothing owed, a check
119
139
  # failed) is the ordinary output of most runs; it is printed to the run summary as a
120
140
  # warning and the job stays green, so a refusal never paints main red for `colab ship`.
@@ -170,6 +190,9 @@ on:
170
190
  # EDIT: when the daily finalize runs (UTC). Off the hour on purpose — the top of the
171
191
  # hour is when scheduled runs queue longest.
172
192
  - cron: "17 3 * * *"
193
+ # #547: the hourly RETRY run — cut only, only when the CLI moved or a run was displaced (header,
194
+ # "A REFUSAL THE HANDBOOK FIXES"). Keep it byte-identical to the string in RETRY_RUN (release job env).
195
+ - cron: "47 * * * *"
173
196
  workflow_dispatch:
174
197
  # #474: a DRY RUN for a fix branch — see "DRY RUN ON A FIX BRANCH" in the header. A dispatch on
175
198
  # any ref other than main is dry whether or not this is set; on main it is opt-in.
@@ -263,6 +286,12 @@ jobs:
263
286
  # Never on workflow_run or schedule. Every write below is off when it is.
264
287
  # EDIT: if your trunk is not `main`, name it here too (the same branch as `ref:` below).
265
288
  DRY_RUN: ${{ github.event_name == 'workflow_dispatch' && (inputs.dry_run || github.ref_name != 'main') }}
289
+ # #547: 'true' on the hourly retry run. EDIT: the cron string here is byte-identical to the hourly
290
+ # `cron:` under `on.schedule`.
291
+ RETRY_RUN: ${{ github.event_name == 'schedule' && github.event.schedule == '47 * * * *' }}
292
+ # EDIT: how recent a move of the CLI still earns a retry. Two hourly runs plus slack, so one
293
+ # scheduled run GitHub drops under load does not lose the retry; a second retry is a no-op.
294
+ RETRY_WINDOW_MINUTES: "130"
266
295
  steps:
267
296
  - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6
268
297
  with:
@@ -334,13 +363,46 @@ jobs:
334
363
  git config user.name "github-actions[bot]"
335
364
  git config user.email "41898282+github-actions[bot]@users.noreply.github.com"
336
365
 
366
+ # #547: on the hourly retry run only — decide whether a cut is worth re-trying (header, "A REFUSAL
367
+ # THE HANDBOOK FIXES"). Ends green either way; retry=true lets the cut step below run.
368
+ - name: Retry a refused cut once the CLI moved (#547)
369
+ id: retry
370
+ if: env.RETRY_RUN == 'true'
371
+ run: |
372
+ set -uo pipefail
373
+ eval "$RETRY_TRANSIENT"
374
+ decide() { echo "retry=$1" >> "$GITHUB_OUTPUT"; echo "Retry run (#547): $2" | tee -a "$GITHUB_STEP_SUMMARY"; exit 0; }
375
+ HEAD="$(git rev-parse HEAD)"
376
+ TAGGED="$(git tag --points-at "$HEAD" --list 'v*' | head -n 1)"
377
+ [ -z "$TAGGED" ] || decide false "main's head ${HEAD:0:7} already carries $TAGGED — nothing to retry."
378
+ # When the CLI reached HANDBOOK_REF: a channel moves onto a release tag's commit, so that
379
+ # tag's date is the move; a plain branch or an untagged commit falls back to the commit date.
380
+ CLI_DIR="${COLAB%/tools/colab}"
381
+ CLI_SHA="$(git -C "$CLI_DIR" rev-parse --short HEAD 2> /dev/null || echo unknown)"
382
+ MOVED="$(git -C "$CLI_DIR" for-each-ref --points-at HEAD --format='%(taggerdate:unix)' refs/tags 2> /dev/null | grep -E '^[0-9]+$' | sort -n | tail -n 1)"
383
+ [ -n "$MOVED" ] || MOVED="$(git -C "$CLI_DIR" log -1 --format=%ct HEAD 2> /dev/null || true)"
384
+ AGE=""; [ -n "$MOVED" ] && AGE=$(( $(date +%s) - MOVED ))
385
+ if [ -n "$AGE" ] && [ "$AGE" -le $(( ${RETRY_WINDOW_MINUTES:-130} * 60 )) ]; then
386
+ decide true "the colab CLI ($CLI_SHA) reached HANDBOOK_REF $(( AGE / 60 )) min ago and main's head ${HEAD:0:7} has no tag — re-trying the cut with it."
387
+ fi
388
+ # A run this one displaced: the newest OTHER run of this workflow at main's head, cancelled.
389
+ # An unreadable list re-tries rather than guessing — a cut with nothing owed is a no-op.
390
+ RUNS="$(retry_transient gh run list --workflow "$GITHUB_WORKFLOW" --commit "$HEAD" --limit 20 --json databaseId,conclusion,createdAt)" \
391
+ || decide true "could not list this workflow's runs at ${HEAD:0:7}, so a displaced run cannot be ruled out — re-trying the cut."
392
+ LAST="$(jq -r --arg me "${GITHUB_RUN_ID:-0}" '[.[] | select((.databaseId | tostring) != $me)] | sort_by(.createdAt) | last | .conclusion // ""' <<< "$RUNS" 2> /dev/null || echo unreadable)"
393
+ case "$LAST" in
394
+ cancelled) decide true "the last run at main's head ${HEAD:0:7} was cancelled (displaced from the shared concurrency group) — doing its cut." ;;
395
+ unreadable) decide true "could not read this workflow's runs at ${HEAD:0:7}, so a displaced run cannot be ruled out — re-trying the cut." ;;
396
+ esac
397
+ decide false "the colab CLI ($CLI_SHA) has not moved in the last ${RETRY_WINDOW_MINUTES:-130} min and no run at ${HEAD:0:7} was displaced — nothing to retry; the daily run cuts as usual."
398
+
337
399
  # #440: where project.yml grants `promotion: main-loop` on `deploy: tag`, promote a green dev
338
400
  # into main, then dispatch CI there — its green run fires this workflow again to cut the
339
401
  # candidate. Everywhere else the CLI answers a no-op. A refusal (dev CI not green, a push
340
402
  # rejected) is a warning; the job stays green.
341
403
  - name: Promote unattended (colab promote --auto)
342
404
  id: promote
343
- if: github.event_name == 'schedule' || github.event_name == 'workflow_dispatch'
405
+ if: (github.event_name == 'schedule' && env.RETRY_RUN != 'true') || github.event_name == 'workflow_dispatch'
344
406
  env:
345
407
  # EDIT: your test-suite workflow — the same one `workflow_run.workflows` names above.
346
408
  CI_WORKFLOW: "CI"
@@ -384,7 +446,7 @@ jobs:
384
446
  # right after this run promoted: that head has no CI yet — the dispatched run cuts it.
385
447
  - name: Cut a candidate (colab release cut --auto)
386
448
  id: cut
387
- if: steps.gate.outputs.cut == 'true' && (github.event_name == 'workflow_run' || github.event_name == 'workflow_dispatch' || github.event_name == 'schedule') && steps.promote.outputs.promoted != 'true'
449
+ if: steps.gate.outputs.cut == 'true' && (github.event_name == 'workflow_run' || github.event_name == 'workflow_dispatch' || github.event_name == 'schedule') && steps.promote.outputs.promoted != 'true' && (env.RETRY_RUN != 'true' || steps.retry.outputs.retry == 'true')
388
450
  run: |
389
451
  set -uo pipefail
390
452
  eval "$RETRY_TRANSIENT"
@@ -444,7 +506,7 @@ jobs:
444
506
 
445
507
  - name: Finalize the newest clean candidate (colab release finalize --auto)
446
508
  id: finalize
447
- if: github.event_name == 'schedule' || github.event_name == 'workflow_dispatch'
509
+ if: (github.event_name == 'schedule' && env.RETRY_RUN != 'true') || github.event_name == 'workflow_dispatch'
448
510
  run: |
449
511
  set -uo pipefail
450
512
  eval "$RETRY_TRANSIENT"