Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
24 changes: 24 additions & 0 deletions .github/dependabot.yml
Original file line number Diff line number Diff line change
@@ -0,0 +1,24 @@
# ext-template's own Dependabot config (not synced into extensions —
# the extensions get template/managed/.github/dependabot.yml instead).
#
# github-actions is enabled for both this repo's workflows and the
# managed workflow templates. A non-root `directory` makes Dependabot
# scan the YAML files directly inside it (dependabot-core
# github_actions/file_fetcher.rb: `workflows_dir = "."` for any
# directory other than "/"), and the unrendered templates parse as
# plain YAML because `{{PLACEHOLDER}}` is a valid flow mapping. A merged
# action bump here reaches every extension on its next bin/sync.
version: 2
updates:
- package-ecosystem: github-actions
directories:
- /
- /template/managed/.github/workflows
schedule:
interval: weekly
day: monday
commit-message:
prefix: "chore(actions)"
groups:
actions:
patterns: ["*"]
16 changes: 12 additions & 4 deletions .github/workflows/ci.yml
Original file line number Diff line number Diff line change
Expand Up @@ -4,6 +4,11 @@ on:
push:
branches: [main]
pull_request:
# Weekly, so a template that silently stopped rendering (a runner or
# shellcheck change) surfaces before the next sync needs it.
schedule:
- cron: '23 6 * * 1'
workflow_dispatch:

env:
FORCE_JAVASCRIPT_ACTIONS_TO_NODE24: "true"
Expand All @@ -18,7 +23,7 @@ jobs:
- name: shellcheck
run: |
sudo apt-get update && sudo apt-get install -y shellcheck
shellcheck bin/render bin/sync bin/lib.sh
shellcheck bin/render bin/sync bin/lib.sh bin/upstream-check

- name: Render smoke test
# Render the example conf and assert (a) every expected file
Expand All @@ -29,8 +34,9 @@ jobs:
bin/render ext-template.conf.example /tmp/ext-example
for f in Makefile build.rs about.toml about.hbs \
.github/workflows/ci.yml .github/workflows/release.yml \
.github/workflows/docs.yml \
.github/workflows/docs.yml .github/dependabot.yml \
Cargo.toml composer.json src/lib.rs src/error.rs \
README.md PLAN.md CHANGELOG.md RELEASE.md \
.cargo/config.toml rust-toolchain.toml .ext-template.conf; do
test -f "/tmp/ext-example/$f" || { echo "missing $f"; exit 1; }
done
Expand All @@ -41,7 +47,9 @@ jobs:
import sys, yaml
for p in ["/tmp/ext-example/.github/workflows/ci.yml",
"/tmp/ext-example/.github/workflows/release.yml",
"/tmp/ext-example/.github/workflows/docs.yml"]:
"/tmp/ext-example/.github/workflows/docs.yml",
"/tmp/ext-example/.github/dependabot.yml",
".github/dependabot.yml"]:
yaml.safe_load(open(p))
print("yaml ok:", p)
'
Expand Down Expand Up @@ -72,5 +80,5 @@ jobs:
sed -i 's/^EXT_PHP_RS_PIN=.*/EXT_PHP_RS_PIN==9.9.9/' template/versions.conf
bin/sync /tmp/ext-example
grep -q 'ext-php-rs = "=9.9.9"' /tmp/ext-example/Cargo.toml
grep -rq '=9.9.9' /tmp/ext-example/rust-toolchain.toml && exit 1 || true
if grep -q '=9.9.9' /tmp/ext-example/rust-toolchain.toml; then exit 1; fi
git checkout -- template/versions.conf
33 changes: 33 additions & 0 deletions .github/workflows/upstream-watch.yml
Original file line number Diff line number Diff line change
@@ -0,0 +1,33 @@
name: Upstream watch

# Weekly check of the exactly-pinned crates Dependabot is told to ignore
# (template/upstream.conf): ext-php-rs and thiserror (owned by
# versions.conf) and each extension's primary upstream crate. One issue
# labelled `upstream` per lagging crate, kept current and closed when the
# pin catches up — so a bump is surfaced without an auto-PR that would
# skip the format and behaviour checks those bumps need.
#
# GitHub disables scheduled workflows in public repos after 60 days with
# no repository activity; Dependabot's weekly github-actions PRs on this
# repo are what keep it alive.

on:
schedule:
- cron: '41 6 * * 1' # Mondays 06:41 UTC, after the extensions' CI
workflow_dispatch:

permissions:
contents: read
issues: write

jobs:
check:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4

- name: Compare pins against crates.io
env:
GH_TOKEN: ${{ github.token }}
GH_REPO: ${{ github.repository }}
run: bin/upstream-check --issues
49 changes: 49 additions & 0 deletions CHANGELOG.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,49 @@
# Changelog

All notable changes to ext-template are documented here. The format is
based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
Extensions pick changes up with `bin/sync`; the version records which
scaffold an extension was synced from.

## [0.2.0] - 2026-10-29

### Added

- Weekly scheduled CI and `workflow_dispatch` in the managed `ci.yml`.
- ZTS test legs (Linux, PHP 8.4 / 8.5), `continue-on-error` for now,
with a step that asserts the runner's `PHP_ZTS` matches the leg.
- Managed `.github/dependabot.yml`: grouped weekly cargo minor/patch,
ignoring the versions.conf pins and each extension's primary upstream
crate.
- ext-template's own Dependabot config for GitHub Actions, covering
`template/managed/.github/workflows`.
- `bin/upstream-check` + `template/upstream.conf` + the weekly
`upstream-watch` workflow: one `upstream` issue per exact pin that
falls behind crates.io.
- Seeds: README Status section, stack table and "Writing about this"
slot; PLAN.md as design notes; CHANGELOG.md.

### Changed

- `EXT_PHP_RS_PIN` `=0.15.13` → `=0.16.3`; `THISERROR_PIN` `=2.0.18` →
`=2.0.21`.
- `make stubs` writes to `target/` for a diff against the curated
stubs, and takes `STUBS_PRELOAD` for Linux.

### Fixed

- Linux CI and release builds on ubuntu-26.04 runners: bindgen's
libclang is pinned to libclang-dev's LLVM (the image mixes clang 20,
21 and 22, which breaks ext-php-rs's bindings generation).
- `make stubs` passed a `--stubs` flag cargo-php never had.
- setup-php is unpinned (`@v2`) and the PHP 8.5 × macos-14 leg is back
(#1, July 2026), now synced into every extension.

## [0.1.0] - 2026-06-12

First release: the `template/managed/` and `template/seed/` trees,
POSIX `bin/render` and `bin/sync`, per-repo `.ext-template.conf`, and
the `versions.conf` pin cascade.

[0.2.0]: https://github.com/DisplaceTech/ext-template/compare/v0.1.0...v0.2.0
[0.1.0]: https://github.com/DisplaceTech/ext-template/releases/tag/v0.1.0
53 changes: 51 additions & 2 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -26,8 +26,8 @@ extensions render from it and re-sync when it improves.

| Tree | Files | Lifecycle |
|---|---|---|
| `template/managed/` | Makefile, build.rs, about.toml/hbs, rust-toolchain.toml, CI/release/docs workflows | **Owned by the template.** Re-rendered into extensions by `bin/sync`; never hand-edit in a child repo. |
| `template/seed/` | Cargo.toml, composer.json, `.cargo/`, src skeleton, docs skeleton, PLAN/RELEASE | **Rendered once** at creation, then owned by the extension. Sync never touches them. |
| `template/managed/` | Makefile, build.rs, about.toml/hbs, rust-toolchain.toml, CI/release/docs workflows, `.github/dependabot.yml` | **Owned by the template.** Re-rendered into extensions by `bin/sync`; never hand-edit in a child repo. |
| `template/seed/` | Cargo.toml, composer.json, `.cargo/`, src skeleton, docs skeleton, README/PLAN/CHANGELOG/RELEASE | **Rendered once** at creation, then owned by the extension. Sync never touches them. |

**Version bumps cascade.** `template/versions.conf` is the single
source of truth for the Rust channel, the declared MSRV, and the crate
Expand Down Expand Up @@ -68,6 +68,55 @@ git -C ../ext-infer diff # review — sync output is a proposal, not a comm
Commit in the child as `chore: sync scaffold from ext-template@<sha>` so
the provenance is greppable.

## Dependency updates and scheduled CI

Naive Dependabot would fight `bin/sync`: a child-side PR bumping a
managed workflow or a versions.conf pin is reverted by the next sync. So
each kind of dependency has exactly one owner:

| Dependency | Owner | How it moves |
| ---------- | ----- | ------------ |
| GitHub Actions (this repo's workflows **and** `template/managed/.github/workflows`) | ext-template's [`.github/dependabot.yml`](.github/dependabot.yml) | Weekly grouped PR here; merge, then `bin/sync` each extension. |
| `ext-php-rs`, `thiserror`, Rust channel | [`template/versions.conf`](template/versions.conf) | Deliberate bump here, cascaded by `bin/sync`; surfaced by the upstream watcher. |
| Each extension's primary upstream crate (`llama-cpp-2`, `turbovec`, `whisper-rs` and their `-sys` crates) | the extension's `Cargo.toml` | Deliberate, tested bump in the extension (format/behaviour checks per its RELEASE.md); surfaced by the upstream watcher. |
| Every other crate in an extension | the managed [`dependabot.yml`](template/managed/.github/dependabot.yml) synced into each child | Weekly grouped minor/patch cargo PR in the child; the classes above are ignored, and `github-actions` is not enabled there. |

**Dependabot and the template path.** Dependabot scans a non-root
`directory` for workflow YAML directly (dependabot-core's
`github_actions/file_fetcher.rb` uses `workflows_dir = "."` for any
directory other than `/`), and the unrendered templates parse as YAML
(`{{PLACEHOLDER}}` is a valid flow mapping; checked with Ruby's
`YAML.safe_load`, the parser Dependabot uses), so action bumps for the
managed workflows land here once.

**Upstream watcher.** [`bin/upstream-check`](bin/upstream-check) reads
[`template/upstream.conf`](template/upstream.conf) and compares each
exact pin Dependabot is told to ignore against crates.io's latest stable
release. The weekly [`upstream-watch`](.github/workflows/upstream-watch.yml)
workflow runs it with `--issues`: one `upstream`-labelled issue per
lagging crate in this repo, kept current as crates.io moves and closed
when the pin catches up. Run `bin/upstream-check` locally for a status
table.

**Scheduled CI.** The managed `ci.yml` runs weekly (Mondays) and on
`workflow_dispatch`, so a green badge means "green this week". GitHub
disables scheduled workflows in public repos after 60 days with no
repository activity; the weekly Dependabot PRs, and merging them, are
what keep the schedules alive. If one goes dormant, re-enable it from
the Actions tab.

**ZTS.** The managed CI matrix adds thread-safe PHP 8.4 and 8.5 legs on
Linux (setup-php `phpts: ts`), `continue-on-error` until they have a
track record. Release binaries stay NTS-only.

## Stubs

Committed stubs are curated (generics, `@throws`, prose), so
`make stubs` writes cargo-php's output to `target/<stubs file>` for a
signature diff instead of overwriting them. On Linux, cargo-php's
`dlopen()` needs PHP's embed library preloaded
(`make stubs STUBS_PRELOAD=/usr/lib/libphp8.4.so`); macOS needs nothing.

## Placeholder convention

Uppercase `{{LIKE_THIS}}`, substituted from `.ext-template.conf` —
Expand Down
109 changes: 109 additions & 0 deletions bin/upstream-check
Original file line number Diff line number Diff line change
@@ -0,0 +1,109 @@
#!/bin/sh
# Report pinned upstream crates that have fallen behind crates.io.
#
# bin/upstream-check # print a status line per crate
# bin/upstream-check --issues # also open/update/close GitHub issues
#
# Reads template/upstream.conf. With --issues (the scheduled workflow),
# keeps exactly one open issue labelled `upstream` per lagging crate in
# the current repo (GH_REPO or the checkout's origin), updates its body
# when crates.io moves again, and closes it once the pin catches up.
# Needs curl and jq; --issues also needs an authenticated gh.
set -eu

TEMPLATE_ROOT=$(CDPATH='' cd -- "$(dirname -- "$0")/.." && pwd)
CONF=$TEMPLATE_ROOT/template/upstream.conf
VERSIONS=$TEMPLATE_ROOT/template/versions.conf
UA="ext-template upstream-check (https://github.com/DisplaceTech/ext-template)"
LABEL=upstream

ISSUES=0
case "${1:-}" in
--issues) ISSUES=1 ;;
'') ;;
*) echo "usage: bin/upstream-check [--issues]" >&2; exit 2 ;;
esac

# Print the exact version a Cargo.toml pins for crate $2, read from
# stdin-less file $1. Handles `crate = "=1.2.3"` and
# `crate = { version = "=1.2.3", ... }`.
cargo_pin() {
sed -n "s/^$2[[:space:]]*=[[:space:]]*\(.*\)$/\1/p" "$1" | head -1 |
sed -e 's/.*version[[:space:]]*=[[:space:]]*//' \
-e 's/^"=\{0,1\}\([^"]*\)".*/\1/'
}

latest_stable() {
curl -fsSL -A "$UA" "https://crates.io/api/v1/crates/$1" |
jq -r '.crate.max_stable_version'
}

# True when $1 sorts strictly before $2 as a version.
older_than() {
[ "$1" != "$2" ] &&
[ "$(printf '%s\n%s\n' "$1" "$2" | sort -V | head -1)" = "$1" ]
}

ensure_label() {
gh label create "$LABEL" --color 0e8a16 \
--description "A pinned upstream crate has a newer release" \
>/dev/null 2>&1 || true
}

# Number of the open upstream issue for crate $1, if any.
open_issue() {
gh issue list --label "$LABEL" --state open --limit 100 \
--json number,title \
--jq ".[] | select(.title | startswith(\"upstream: $1 \")) | .number" |
head -1
}

tmp=$(mktemp)
trap 'rm -f "$tmp"' EXIT
[ "$ISSUES" -eq 0 ] || ensure_label

grep -v '^[[:space:]]*#' "$CONF" | grep -v '^[[:space:]]*$' |
while read -r source crate key; do
if [ "$source" = versions.conf ]; then
pinned=$(sed -n "s/^$key==\{0,1\}//p" "$VERSIONS" | head -1)
where="ext-template template/versions.conf ($key)"
else
curl -fsSL "https://raw.githubusercontent.com/$source/HEAD/Cargo.toml" -o "$tmp"
pinned=$(cargo_pin "$tmp" "$crate")
where="$source Cargo.toml"
fi
latest=$(latest_stable "$crate")
if [ -z "$pinned" ] || [ -z "$latest" ] || [ "$latest" = null ]; then
echo "error: could not resolve $crate (pinned='$pinned' latest='$latest')" >&2
exit 1
fi

if older_than "$pinned" "$latest"; then
echo "BEHIND $crate =$pinned -> $latest ($where)"
else
echo "ok $crate =$pinned ($where)"
fi

[ "$ISSUES" -eq 1 ] || continue
number=$(open_issue "$crate")
if older_than "$pinned" "$latest"; then
title="upstream: $crate $latest available (pinned =$pinned)"
body="\`$crate\` **$latest** is the latest stable release on crates.io; $where pins **=$pinned**.

Upstream bumps are deliberate, tested events, not Dependabot PRs. Before bumping:

- read the changelog between the two versions (https://crates.io/crates/$crate/versions);
- for ext-php-rs / thiserror: bump \`template/versions.conf\`, then \`bin/sync\` each extension and diff its regenerated stubs — any PHP signature change is a stop-and-decide;
- for a primary upstream crate: follow that extension's RELEASE.md upstream-bump procedure (format compatibility, behavioural re-verification, THIRD-PARTY-NOTICES).

Opened by the scheduled upstream watcher (\`bin/upstream-check --issues\`); it updates this issue if crates.io moves again and closes it once the pin catches up."
if [ -n "$number" ]; then
gh issue edit "$number" --title "$title" --body "$body" >/dev/null
echo " updated #$number"
else
gh issue create --label "$LABEL" --title "$title" --body "$body"
fi
elif [ -n "$number" ]; then
gh issue close "$number" --comment "The pin is now =$pinned, which is current. Closing."
fi
done
38 changes: 38 additions & 0 deletions template/managed/.github/dependabot.yml
Original file line number Diff line number Diff line change
@@ -0,0 +1,38 @@
# Template-managed (ext-template): edit upstream in
# template/managed/.github/dependabot.yml, then bin/sync. See the
# "Dependency updates" section of ext-template's README for the design.
#
# Weekly, grouped minor/patch updates for the crates this extension owns.
# Three classes of dependency are deliberately excluded:
#
# - ext-php-rs, thiserror: their pins live in ext-template's
# template/versions.conf and cascade through bin/sync. A Dependabot PR
# here would be reverted by the next sync.
# - The primary upstream crate (llama-cpp-2 / turbovec / whisper-rs and
# their -sys crates): bumps are deliberate, tested events with format
# and behaviour checks. ext-template's scheduled upstream watcher opens
# an issue when one falls behind crates.io instead of a PR.
# - GitHub Actions: every workflow in this repo is template-managed.
# ext-template's own Dependabot config bumps action versions in
# template/managed/, and bin/sync carries them here.
version: 2
updates:
- package-ecosystem: cargo
directory: /
schedule:
interval: weekly
day: monday
open-pull-requests-limit: 5
commit-message:
prefix: "chore(deps)"
groups:
cargo-minor-patch:
update-types: [minor, patch]
ignore:
- dependency-name: ext-php-rs
- dependency-name: thiserror
- dependency-name: llama-cpp-2
- dependency-name: llama-cpp-sys-2
- dependency-name: turbovec
- dependency-name: whisper-rs
- dependency-name: whisper-rs-sys
Loading
Loading