Skip to content

WORKFLOW.md

Latest commit

 

History

History
128 lines (96 loc) · 5.67 KB

WORKFLOW.md

File metadata and controls

128 lines (96 loc) · 5.67 KB
Raw

Blog publishing workflow

How posts get written, reviewed, and shipped. Three environments:

where who sees it notes
local make preview on localhost you live-reload while drafting
preview https://<preview-branch>.generality-site.pages.dev anyone with the link auto-built for preview/* branches; link posted on the PR
prod GitHub Pages → generality.org everyone served from main; clean by construction

0. Toolchain

make setup        # once per machine: fetches the pinned Quarto into .tools/

Rendered HTML is committed and served as-is, so everyone must render with the same Quarto version — the pin lives in the Makefile (QUARTO_VERSION); make render and make preview use it.

1. Start a post

scripts/new-post.sh my-post-slug "My Post Title" ["Author Name"]

Scaffolds blog/posts/my-post-slug/ on the shared site shell (_includes/ partials + assets/site.css; only the title block _header.html is post-local), a data/ directory for figure data contracts, and a qmd skeleton that imports gl.js (figure components) and model-colors.js (provider identity).

Figures follow a three-layer architecture: an export script in the analysis repo writes a small JSON data contract into data/; an OJS cell feeds it to a gl component. Keep the export script checked in next to the analysis.

2. Draft locally

make preview POST=blog/posts/my-post-slug   # live-reloading Quarto preview

Edit index.qmd, save, watch it re-render. This is the standard local flow.

There is also an experimental in-place WYSIWYG prose editor (python3 scripts/edit-server.py, serves on :8787), but it's a local-only convenience — not part of the shared workflow and still rough around inline links/footnotes. Prefer make preview + editing the .qmd.

3. Preview for review

Put your work on a branch under the preview/ prefix, render, and push:

git switch -c preview/my-post-slug
make render                                  # commit the rendered HTML
git commit -am "draft: my post" && git push -u origin preview/my-post-slug

Cloudflare Pages auto-builds any preview/* branch; open a PR from it and the Cloudflare bot comments the preview URL on the PR. Use the stable Branch Preview URL (preview-my-post-slug.generality-site.pages.dev) — it survives re-pushes, so review links persist as you iterate. Only preview/* branches build; any other branch stays silent (no preview, no comment).

Inline on-page commenting isn't wired up yet — review via the preview link + PR comments for now. (A hosted annotation layer is a possible future add.)

4. Ship to prod

Prod is GitHub Pages served from main → generality.org (CNAME). Static: the rendered index.html and data/ are committed, so a merge to main is the deploy. Merge the post branch into main. Before shipping:

  • remove the "Draft" eyebrow from the post's _header.html,
  • add a card for the post to blog/index.html (the index is hand-maintained — copy an existing <a class="post-card"> block).

Branch hygiene

One branch per post, PR'd into main. Use the preview/ prefix for anything you want a preview link for; reconcile to main deliberately.

Shared Quarto runtime

A post-render hook (scripts/share_quarto_libs.py) hoists each rendered post's private index_files/libs/ (~1MB of Quarto/OJS runtime) into version-scoped assets/quarto-libs/, so readers cache it once across posts. Version-scoped on purpose: a toolchain bump creates a sibling dir rather than mutating libs that already-shipped posts reference.

Hosting

  • Prod: GitHub Pages, from main → generality.org (the CNAME file).
  • Previews: the generality-site Cloudflare Pages project (Git-connected), builds preview/* branches and comments preview links on PRs. No token, no manual deploy.

Live data (RLI auto-update)

.github/workflows/update-rli.yml runs scripts/update_rli.py weekly. It scrapes the Scale RLI leaderboard (labs.scale.com/leaderboard/rli, a static HTML table), appends any new models to the forecasting-the-remote-labor-index post's data/rli.json (dated at appearance, effort-configs collapsed to best score), and commits to main — so new models surface as out-of-sample stars on the final forecast graph without touching the frozen fit. Needs repo Actions to have write permission (Settings → Actions → Workflow permissions). Stdlib-only, so no dependency install in the runner.

The forecasting-the-remote-labor-index figure data is generated by the analysis pipeline in the sibling ../saturation/ repo (see its PIPELINE.md; ./run_all.sh regenerates every data contract from the committed *_raw.json sources).

Pieces

  • Makefile — pinned Quarto toolchain (make setup/render/preview)
  • _quarto.yml — project config: render list + shared-libs post-render hook
  • _includes/ + assets/site.css — shared site shell for posts
  • scripts/share_quarto_libs.py — post-render hook deduplicating Quarto libs
  • assets/gl-components/gl.js — figure component library (house style lives here)
  • assets/gl-components/model-colors.js — canonical provider colours/names
  • scripts/new-post.sh — scaffold
  • scripts/update_rli.py — scrape Scale leaderboard, append new RLI models
  • .github/workflows/update-rli.yml — weekly RLI auto-update cron
  • scripts/edit-server.py, assets/gl-edit/ — experimental local in-place editor (not part of the shared flow)
  • assets/gl-comments/, review/ — legacy bespoke review-comment system (currently unused; inline comments TBD)
  • style-lab/ — graph house-style workshop (internal)