@futurelastic/colab-handbook 1.18.0-rc.3 → 1.18.0-rc.4

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.18.0-rc.3"
36
+ "version": "1.18.0-rc.4"
37
37
  }
@@ -34,6 +34,11 @@
34
34
  # (A tag pushed or a Release published with GITHUB_TOKEN starts no other workflow, so a chained call is
35
35
  # the reliable trigger — not `on: release`.) Nothing is published from an incomplete Release: the script
36
36
  # names what is missing and uploads nothing.
37
+ # Chained from release-auto.yml, gate the build jobs and this one on its `downloads-tag` output, not on
38
+ # the run's own finalize tag (#669): `downloads-tag` also carries a final a PERSON tagged — early
39
+ # (`colab release finalize --early`, #627) or on `final: human` — which no run tags, and which the daily
40
+ # run hands on once the site's latest.json is behind it (creating its Release, so the build jobs have one
41
+ # to attach files to). release-auto.yml's "DOWNLOADS" header block shows the wiring.
37
42
  # - By hand (Actions → Run workflow) with a tag: retries a failed publish, finishes a partial one (only the
38
43
  # missing files are sent), re-checks a complete one. `dry_run` stages and lists — it uploads nothing.
39
44
  # The project.yml, manifest, installers and script are read from THIS run's checkout: the tag's commit when
@@ -31,6 +31,11 @@
31
31
  # comment above that job
32
32
  # the daily schedule or a dispatch, and the same npm publish of the newest final on main
33
33
  # npm `latest` is older than that final — a final tagged by hand (`final: human`, #612)
34
+ # project.yml declares `downloads:`, and the final this run tagged — or, on the daily
35
+ # this run tagged a final, or the daily schedule / a dispatch, the newest final on main
36
+ # schedule / a dispatch finds the site's (an early or `final: human` final a person
37
+ # latest.json older than the newest final tagged, #669) — handed to YOUR build + downloads
38
+ # jobs as `downloads-tag`; see "DOWNLOADS" below
34
39
  # the cut tagged a FINAL — route deploy + health check (job `deploy`, #446) — see
35
40
  # deploy-tag-fast only "DEPLOYING IN THIS RUN" below
36
41
  # the cut tagged a FINAL — route published like any tag (Release marked latest, npm
@@ -126,6 +131,38 @@
126
131
  # ends in `[publish]`. So a red INSIDE a `[publish]` step, or in the npm or deploy jobs (which never
127
132
  # run without a tag), cannot be cured by a dry run — that stays a human ci-grant.
128
133
  #
134
+ # DOWNLOADS — EVERY FINAL, NOT ONLY THE ONES THIS RUN TAGGED (#669). A repo whose finals carry files
135
+ # people install (docs/downloads.md, templates/publish-downloads.yml) builds them in jobs YOU add below
136
+ # `release`, and chains publish-downloads.yml after them. Gate both on the release job's
137
+ # `downloads-tag` output, never on the finalize step's own tag: a final a person tagged — early
138
+ # (`colab release finalize --early`, #627) or on `final: human` — is tagged by the CLI, not by this
139
+ # run, so a job gated on this run's tag never builds it, and a later run reads `already-final` and
140
+ # skips it again. `downloads-tag` is the final this run tagged, or — on the daily run and a dispatch —
141
+ # the newest final on main whose version the site's latest.json does not name yet (absent, or older);
142
+ # that swept final also gets its GitHub Release here, so your build jobs have one to attach files to.
143
+ # Empty when project.yml declares no `downloads:`, when the site already names that version or a newer
144
+ # one (a complete version sends nothing), and when the site cannot be read from this job's runner —
145
+ # a warning then, never a red run; the next daily run retries. The site is read at
146
+ # vars.DOWNLOADS_URL/<downloads.app>/latest.json FROM THE RELEASE JOB'S RUNNER: a site only a private
147
+ # network reaches needs the release job on a runner inside it (RUNNERS, below). The wiring:
148
+ #
149
+ # build-macos: # EDIT: one job per platform you build
150
+ # needs: release
151
+ # if: needs.release.outputs.downloads-tag != ''
152
+ # runs-on: macos-latest
153
+ # permissions: { contents: write }
154
+ # steps:
155
+ # - uses: actions/checkout@<sha>
156
+ # with: { ref: '${{ needs.release.outputs.downloads-tag }}' }
157
+ # - run: …build, then attach the files to the tag's Release (gh release upload … --clobber)
158
+ # env: { GH_TOKEN: '${{ github.token }}', TAG: '${{ needs.release.outputs.downloads-tag }}' }
159
+ # downloads:
160
+ # needs: [release, build-macos]
161
+ # if: needs.release.outputs.downloads-tag != ''
162
+ # uses: ./.github/workflows/publish-downloads.yml
163
+ # with: { tag: '${{ needs.release.outputs.downloads-tag }}' }
164
+ # secrets: inherit
165
+ #
129
166
  # IT READS TAGS AND CREATES TAGS. IT NEVER WRITES A COMMIT. No step here commits; the refs
130
167
  # pushed are the tags `colab release cut` / `colab release finalize` create (annotated, their
131
168
  # checks recorded in the tag message) and — only on a repo granting unattended promotion — the
@@ -335,6 +372,10 @@ jobs:
335
372
  # What the deploy job below needs (#446) — empty unless this run tagged a deploy-tag-fast final.
336
373
  deploy-tag: ${{ steps.cut.outputs.final }}
337
374
  health-url: ${{ steps.cut.outputs.health-url }}
375
+ # What YOUR build and downloads jobs gate on (#669) — empty unless project.yml declares `downloads:`
376
+ # and this run tagged a final, or the daily sweep found a final the site's latest.json lacks.
377
+ # See "DOWNLOADS" in the header.
378
+ downloads-tag: ${{ steps.downloads-target.outputs.tag }}
338
379
  env:
339
380
  GH_TOKEN: ${{ github.token }}
340
381
  # #474: 'true' on a dry run — a dispatch on any ref other than main, or one with dry_run set.
@@ -776,12 +817,83 @@ jobs:
776
817
  echo "package=$PACKAGE"
777
818
  } >> "$GITHUB_OUTPUT"
778
819
 
779
- # Publishes every tag THIS run created. In this run, never via a tag-push workflow:
780
- # see "PUBLISHING HAPPENS IN THIS RUN" in the header.
781
- - name: Publish GitHub Release (same run) [publish]
782
- if: env.DRY_RUN != 'true' && (steps.cut.outputs.tag != '' || steps.finalize.outputs.tag != '')
820
+ # #669: which final YOUR build + downloads jobs get (`downloads-tag`, header "DOWNLOADS"). The final
821
+ # this run tagged, if any; else, on the daily run and a dispatch, the newest FINAL reachable from main
822
+ # when the site's latest.json does not name it yet (absent → never published, older → behind) — a
823
+ # final a person tagged (early, #627, or `final: human`) is never tagged by a run, so without this
824
+ # sweep it never reached the site. The site at that version or newer, no `downloads:` block, no
825
+ # DOWNLOADS_URL, or an unreadable site: nothing is handed on, and the step stays green.
826
+ - name: Read the downloads target [publish]
827
+ id: downloads-target
828
+ if: env.DRY_RUN != 'true' && (steps.cut.outputs.tag != '' || steps.finalize.outputs.tag != '' || (github.event_name == 'schedule' && env.RETRY_RUN != 'true') || github.event_name == 'workflow_dispatch')
783
829
  env:
784
830
  TAGS: ${{ steps.cut.outputs.tag }} ${{ steps.finalize.outputs.tag }}
831
+ SWEEP: ${{ (github.event_name == 'schedule' && env.RETRY_RUN != 'true') || github.event_name == 'workflow_dispatch' }}
832
+ DOWNLOADS_URL: ${{ vars.DOWNLOADS_URL }}
833
+ run: |
834
+ set -uo pipefail
835
+ # The `downloads:` block's `app:` — the same key publish-downloads.mjs reads. No block, no target.
836
+ APP="$(awk '
837
+ /^downloads:[ \t]*(#.*)?$/ { inb = 1; next }
838
+ inb && /^[^ \t#]/ { exit }
839
+ inb && /^[ \t]+app:/ { v = $0; sub(/^[ \t]+app:[ \t]*/, "", v); sub(/[ \t]+#.*$/, "", v); gsub(/["\047]/, "", v); sub(/[ \t]+$/, "", v); print v; exit }
840
+ ' .github/project.yml 2> /dev/null)"
841
+ if [ -z "$APP" ]; then
842
+ echo "No downloads: block in .github/project.yml — no downloads target."
843
+ exit 0
844
+ fi
845
+ if ! [[ "$APP" =~ ^[a-z0-9][a-z0-9-]*$ ]]; then
846
+ echo "::warning::downloads.app '$APP' is not a valid app slug — nothing is handed to the downloads jobs"
847
+ exit 0
848
+ fi
849
+ OWN="$(tr ' ' '\n' <<< "$TAGS" | grep -E '^v[0-9]+\.[0-9]+\.[0-9]+$' | sort -V | tail -n 1 || true)"
850
+ if [ -n "$OWN" ]; then
851
+ echo "tag=$OWN" >> "$GITHUB_OUTPUT"
852
+ echo "downloads: $OWN was tagged by this run — handing it to the build and downloads jobs" | tee -a "$GITHUB_STEP_SUMMARY"
853
+ exit 0
854
+ fi
855
+ [ "${SWEEP:-false}" = "true" ] || exit 0
856
+ FINAL="$(git tag --merged HEAD --list 'v*' | grep -E '^v[0-9]+\.[0-9]+\.[0-9]+$' | sort -V | tail -n 1 || true)"
857
+ if [ -z "$FINAL" ]; then
858
+ echo "downloads sweep: no final on main yet — nothing to publish"
859
+ exit 0
860
+ fi
861
+ if [ -z "${DOWNLOADS_URL:-}" ]; then
862
+ echo "::warning::downloads sweep: the DOWNLOADS_URL variable is not set on this repo — cannot read the site, so $FINAL is not handed on"
863
+ exit 0
864
+ fi
865
+ eval "$RETRY_TRANSIENT"
866
+ VERSION="${FINAL#v}"
867
+ URL="${DOWNLOADS_URL%/}/$APP/latest.json"
868
+ ERR="$RUNNER_TEMP/downloads-latest.err"
869
+ hand_on() {
870
+ { echo "tag=$FINAL"; echo "swept=$FINAL"; } >> "$GITHUB_OUTPUT"
871
+ echo "downloads sweep: $1 — handing $FINAL to the build and downloads jobs (#669)" | tee -a "$GITHUB_STEP_SUMMARY"
872
+ }
873
+ if BODY="$(retry_transient curl -fsSL "$URL" 2> "$ERR")"; then
874
+ SITE="$(jq -r '.version // empty' <<< "$BODY" 2> /dev/null || true)"
875
+ if [ -z "$SITE" ]; then
876
+ echo "::warning::downloads sweep: $URL names no version — $FINAL is not handed on in this run"
877
+ elif [ "$SITE" = "$VERSION" ]; then
878
+ echo "downloads sweep: the site already names $VERSION — nothing to publish"
879
+ elif [ "$(printf '%s\n' "$SITE" "$VERSION" | sort -V | tail -n 1)" = "$SITE" ]; then
880
+ echo "downloads sweep: the site names $SITE, newer than $FINAL — nothing to publish" | tee -a "$GITHUB_STEP_SUMMARY"
881
+ else
882
+ hand_on "$FINAL is final on main but the site names $SITE"
883
+ fi
884
+ elif grep -q 'error: 404' "$ERR"; then
885
+ hand_on "$FINAL is final on main and the site has no latest.json for $APP"
886
+ else
887
+ echo "::warning::downloads sweep: could not read $URL from this runner ($(tail -n 1 "$ERR" 2> /dev/null)) — $FINAL is not handed on in this run; the next daily run retries"
888
+ fi
889
+
890
+ # Publishes every tag THIS run created — and a final the downloads sweep handed on (#669), which a
891
+ # person tagged and nothing published. In this run, never via a tag-push workflow: see "PUBLISHING
892
+ # HAPPENS IN THIS RUN" in the header.
893
+ - name: Publish GitHub Release (same run) [publish]
894
+ if: env.DRY_RUN != 'true' && (steps.cut.outputs.tag != '' || steps.finalize.outputs.tag != '' || steps.downloads-target.outputs.swept != '')
895
+ env:
896
+ TAGS: ${{ steps.cut.outputs.tag }} ${{ steps.finalize.outputs.tag }} ${{ steps.downloads-target.outputs.swept }}
785
897
  run: |
786
898
  set -euo pipefail
787
899
  eval "$RETRY_TRANSIENT"