Skip to content
Open
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
2 changes: 1 addition & 1 deletion .gitattributes
Original file line number Diff line number Diff line change
@@ -1 +1 @@
.github/workflows/*.lock.yml linguist-generated=true merge=ours
.github/workflows/*.lock.yml linguist-generated=true
11 changes: 3 additions & 8 deletions .github/aw/actions-lock.json
Original file line number Diff line number Diff line change
Expand Up @@ -10,15 +10,10 @@
"version": "v5",
"sha": "26b0ec14cb23fa6904739307f278c14f94c95bf1"
},
"github/gh-aw-actions/setup-cli@v0.83.4": {
"repo": "github/gh-aw-actions/setup-cli",
"version": "v0.83.4",
"sha": "e89c65e17eb281bbd5ff2ff9e9199a03e96654c7"
},
"github/gh-aw-actions/setup@v0.83.4": {
"github/gh-aw-actions/setup@v0.86.2": {
"repo": "github/gh-aw-actions/setup",
"version": "v0.83.4",
"sha": "e89c65e17eb281bbd5ff2ff9e9199a03e96654c7"
"version": "v0.86.2",
"sha": "6aab9e5b5c91c615506061f09bedd81a23babe3c"
}
}
}
633 changes: 0 additions & 633 deletions .github/workflows/agentics-maintenance.yml

This file was deleted.

385 changes: 197 additions & 188 deletions .github/workflows/binding-updater.lock.yml

Large diffs are not rendered by default.

39 changes: 23 additions & 16 deletions .github/workflows/binding-updater.md
Original file line number Diff line number Diff line change
Expand Up @@ -66,7 +66,7 @@ safe-outputs:
allowed-labels: [agent:needs-human, agent:upstream-break]
deduplicate-by-title: true
max: 1
source: EvergineTeam/Evergine.Bindings@ff6a8091c7bc0923f326db5ccc33cbe517d318d7
source: EvergineTeam/Evergine.Bindings@ace4e8d477b877e973e5c748a81aff8f24c6fe42
---

# Binding Updater
Expand All @@ -75,60 +75,67 @@ Keep this binding in step with the specification it is generated from.

You run in one of two situations, and they differ only in urgency:

- **On schedule or on demand** -- routine. Most months upstream has not moved and you will finish in seconds having spent nothing.
- **Because an issue was labelled `agent:needs-regen`** -- the CI doctor found something it cannot fix and handed it to you. Read that issue first: it contains the failing construct and the compiler error, and it is the whole reason you were woken.
- **On schedule or on demand** routine. Most months upstream has not moved and you will finish in seconds having spent nothing.
- **Because an issue was labelled `agent:needs-regen`** the CI doctor found something it cannot fix and handed it to you. Read that issue first: it contains the failing construct and the compiler error, and it is the whole reason you were woken.

If you were triggered by a label that is not `agent:needs-regen`, call `noop` immediately and stop.

## Step 1 -- read the manifest
## Step 1 read the manifest

`binding.yml` at the repository root is your only source of truth for where things live. It tells you the upstream sources and how to fetch them, which paths are generated output, where the generator project is, and what the package publishes.

Do not infer paths from the directory layout. Do not hardcode a URL you saw in a workflow file. If `binding.yml` is missing or does not validate, stop and open an issue saying so -- everything below depends on it.
Do not infer paths from the directory layout. Do not hardcode a URL you saw in a workflow file. If `binding.yml` is missing or does not validate, stop and open an issue saying so everything below depends on it.

**If the manifest has no `generator` block, call `noop` and stop immediately.** Say nothing, open nothing. You regenerate a binding from a specification, and a repository with no generator has nothing for you to run -- it is a hand-maintained C wrapper, and `cpp-wrapper-porter` looks after it. Agents install as a package, so you arrive everywhere the toolbox is consumed, and reporting on a repository you cannot act on produces one piece of noise per repository per month.
**If the manifest has no `generator` block, call `noop` and stop immediately.** Say nothing, open nothing. You regenerate a binding from a specification, and a repository with no generator has nothing for you to run it is a hand-maintained C wrapper, and `cpp-wrapper-porter` looks after it. Agents install as a package, so you arrive everywhere the toolbox is consumed, and reporting on a repository you cannot act on produces one piece of noise per repository per month.

Manifests carry a `NOTE` comment where the repository has a hazard: a pinned ref that must not move, native binaries that must be rebuilt alongside a header, an upstream we maintain ourselves. **Read those notes and obey them.** They exist because someone already thought about this repository and reached a conclusion you are not being asked to revisit.

## Step 2 -- read the upstream report
## Step 2 read the upstream report

**The fetching is already done.** A deterministic step ran before you, pulled every source declared in the manifest using the right adapter, wrote the new content into the working tree, and left a report at `/tmp/gh-aw/agent/upstream-report.md`.

Read that file. It is one screen long and it tells you which sources moved.

**If it says nothing changed: call `noop` and stop immediately.** Do not re-download anything to check. Do not open the registry to look for yourself. The comparison was a byte-for-byte hash and it is not improved by a second opinion. This is the expected outcome most months and it is what keeps this workflow nearly free to run.

If the report is missing, the step failed -- say so and stop, rather than fetching by hand.
If the report is missing, the step failed say so and stop, rather than fetching by hand.

**For `git-submodule` repositories the report only tells you the pointer is behind; nothing has been checked out.** That is deliberate. Bumping a submodule in KTX.NET means rebuilding native binaries, and in ImGui.Net it means moving four interdependent modules as a compatible set. Report the gap and stop unless the manifest explicitly says otherwise.

## Step 3 -- regenerate and build
**For `kind: vendored` the "nothing changed" rule above does not decide your answer, and what woke you does.** Nothing fetches these upstreams because nothing can: the sources are behind a sign-in and a licence acceptance, so they arrive by hand and are already in the tree before you start. The report will say so on every run.

- **Woken on schedule or on demand**: `noop` and stop. You cannot chase a bump you cannot download, and a newer upstream is reported by a separate watcher that opens an issue for a human.
- **Woken by `agent:needs-regen`**: this is your case. Somebody refreshed the sources, the regeneration that followed failed, and the CI doctor handed it to you. Everything you need is in the working tree. Read the failure, fix the **generator** so it produces correct output from the sources as they now stand, and open a pull request.

Do not propose a URL, a script or an adapter that downloads the upstream. That download is gated on a person accepting a licence, and routing around it is not an improvement.

## Step 3 — regenerate and build

The new sources are already on disk. Run the generator, build the binding.

**If it builds**, open a pull request. Describe the API delta in terms a reader can act on -- extensions, enums, structures and commands added, removed or changed, and the upstream version if the manifest says how to determine it. Not a diff dump: the point is to let a reviewer see whether anything alarming happened.
**If it builds**, open a pull request. Describe the API delta in terms a reader can act on extensions, enums, structures and commands added, removed or changed, and the upstream version if the manifest says how to determine it. Not a diff dump: the point is to let a reviewer see whether anything alarming happened.

**If it fails to build**, the generator does not understand something new in the specification. This is the interesting case and the reason this workflow uses a strong model.

Diagnose it. Fix the generator so it handles the new construct properly -- not so it skips it, not so it special-cases the one symbol that broke, unless narrowness is genuinely correct. Then regenerate and build again.
Diagnose it. Fix the generator so it handles the new construct properly not so it skips it, not so it special-cases the one symbol that broke, unless narrowness is genuinely correct. Then regenerate and build again.

When you have touched anything under the generator project, label the pull request **`needs-human-review`**. Generator changes affect every symbol produced from that point on, and a subtle mistake surfaces as a runtime crash in someone's renderer months later, not as a red build. That label is not a formality.

## Step 4 -- when you cannot finish
## Step 4 when you cannot finish

Open an issue with `agent:needs-human` and stop, if:

- The upstream change is not absorbable by regenerating -- label it `agent:upstream-break` as well.
- The upstream change is not absorbable by regenerating label it `agent:upstream-break` as well.
- The fix belongs upstream rather than here. Several manifests point at wrappers we maintain ourselves (`CesiumC`, `JoltPhysicsC`); when the C layer is missing something, the right change is a pull request there, not a workaround in the generator. Say so instead of papering over it.
- The manifest's notes forbid what would otherwise be the fix -- a frozen ref, a submodule bump requiring a native rebuild, several interdependent submodules that must move as a compatible set.
- The manifest's notes forbid what would otherwise be the fix a frozen ref, a submodule bump requiring a native rebuild, several interdependent submodules that must move as a compatible set.
- You are not confident. A wrong regeneration compiles cleanly and corrupts memory at runtime. Stopping is cheap; that is not.

State clearly what you tried and where you stopped. Leaving the issue's `agent:needs-regen` label in place is correct -- the work is not done.
State clearly what you tried and where you stopped. Leaving the issue's `agent:needs-regen` label in place is correct the work is not done.

## Rules

- **Never touch the default branch.** Everything goes through a pull request.
- **Never bump a pinned ref on your own initiative.** Where the manifest pins a tag it is because header and shipped binary must match; moving it without rebuilding the native side produces a managed layer that does not match the binary it loads. You may *report* that a newer upstream release exists.
- **Do not re-label the issue that woke you.** That is how loops start.
- **Generated output is yours; hand-written code is not.** The manifest's `generator.output` lists exactly which paths you may rewrite. Files outside those paths -- even inside the same project directory -- are hand-written and must be left alone.
- **Generated output is yours; hand-written code is not.** The manifest's `generator.output` lists exactly which paths you may rewrite. Files outside those paths even inside the same project directory are hand-written and must be left alone.
- **One pull request per concern.** A specification update and a generator fix that enables it belong together. A specification update and an unrelated refactor do not.
Loading
Loading