Skip to content

Clarify embed control, build process, and delivery architecture #91

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
oblomov-dev merged 1 commit into from
Oct 12, 2026
Merged

Clarify embed control, build process, and delivery architecture #91

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
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
5 changes: 4 additions & 1 deletion .github/pull_request_template.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -11,7 +11,10 @@
deliver workflow rewrites each branch as one commit on top
of main with its folder's content. Change it there: the
webapp in app/webapp/ (then run 'npm run app2abap'), the
ABAP artefacts in frontend/, the build in tools/.
app of standard_new and cloud_new in frontend/embed/, the
ABAP artefacts in frontend/abap/, the build in tools/.
The embed control those two branches hold
(z2ui5.embed.Container) is abap2UI5/embed-control's.
main carries this repository's own docs plus the machine-written
result/ trees - the docs are the only thing maintained here.

Expand Down
12 changes: 7 additions & 5 deletions .github/workflows/deliver.yaml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -2,11 +2,13 @@ name: deliver

# The second half of the delivery relay.
#
# abap2UI5/abap2UI5 builds the six published branches, commits them there as
# reviewed trees (build/<branch>), and its frontend_deploy workflow writes the
# stamped result as result/<branch> folders into ONE commit on main here. This
# workflow is what turns those folders into the branches an abapGit repository
# actually pulls: on every push to main it writes, per branch, one commit
# abap2UI5/abap2UI5 builds the six published branches at deploy time - into
# its git-ignored tools/out/, the same build its frontend_check gate ran on
# the pull request; no tree is committed on that side - and its
# frontend_deploy workflow writes the stamped result as result/<branch>
# folders into ONE commit on main here. This workflow is what turns those
# folders into the branches an abapGit repository actually pulls: on every
# push to main it writes, per branch, one commit
#
# parent = the main commit
# tree = the content of result/<branch>, nothing else
Expand Down
4 changes: 4 additions & 0 deletions .github/workflows/guard.yaml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -115,6 +115,10 @@ jobs:
echo " -> abap2UI5/abap2UI5, in app/webapp/"
echo " run 'npm run app2abap' there to regenerate src/01/03,"
echo " and the frontend_deploy workflow delivers it here."
echo " the app of standard_new and cloud_new (around the embed control)"
echo " -> abap2UI5/abap2UI5, in frontend/embed/."
echo " the embed control itself (z2ui5.embed.Container)"
echo " -> abap2UI5/embed-control, published as @abap2ui5/embed-control."
echo " the ABAP handlers, the packaging, the build"
echo " -> abap2UI5/abap2UI5, in frontend/ and tools/."
echo " a bug report or a feature request"
Expand Down
69 changes: 53 additions & 16 deletions AGENTS.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,10 +1,8 @@
# AGENTS.md — AI Assistant Guide for abap2UI5 frontend

> This file follows the cross-tool AGENTS.md convention and is the single
> agent instruction file of this repository. `CLAUDE.md` exists next to it
> and is a pointer at this file, nothing more — CONVENTIONS §6 asks for one
> in every repository that has an AGENTS.md. This paragraph used to claim
> there was no `CLAUDE.md` while the file sat beside it.
> agent instruction file of this repository. `CLAUDE.md` next to it is a
> pointer at this file, nothing more.

## Do Not Open Pull Requests Here

Expand All @@ -17,6 +15,10 @@ Before you change anything, work out where the change belongs:
[abap2UI5/abap2UI5](https://github.com/abap2UI5/abap2UI5), run
`npm run app2abap` there to regenerate `src/01/03`, and its `frontend_deploy`
workflow delivers the result into the branches here.
* **The app of `standard_new` and `cloud_new`** → not here. It is
[`frontend/embed`](https://github.com/abap2UI5/abap2UI5/tree/main/frontend/embed)
in abap2UI5, with its own `AGENTS.md`. The control it holds is not there
either — see "The embed control" below.
* **The ABAP handlers, the BSP packaging, the build** → not here either. They
live in abap2UI5 as well: the ABAP artefacts and the files every branch
inherits in
Expand All @@ -25,12 +27,11 @@ Before you change anything, work out where the change belongs:
[`tools/`](https://github.com/abap2UI5/abap2UI5/tree/main/tools).
* **Any branch except `main`, and `result/` on `main`** → not here. `cloud`,
`cloud_v2`, `standard`, `standard_v2`, `cloud_new` and `standard_new` are
built in abap2UI5 (`tools/build-branches.mjs`; the app of the `_new`
branches is its `frontend/embed`) and its `frontend_deploy` workflow
delivers them into `result/<branch>` on `main` here, and the `deliver` workflow rewrites each
branch as one commit on top of `main` carrying its folder's content;
`standard_<name>` is built by `frontend_deploy` on demand and pushed onto
its branch directly.
built in abap2UI5 (`tools/build-branches.mjs`) and its `frontend_deploy`
workflow delivers them into `result/<branch>` on `main` here, and the
`deliver` workflow rewrites each branch as one commit on top of `main`
carrying its folder's content; `standard_<name>` is built by
`frontend_deploy` on demand and pushed onto its branch directly.
* **The repository docs** → here, and only here — nothing generates
them. This is a *maintenance* change: it targets `main`, adds no source
files, and stays blocked until a **human maintainer** applies the
Expand Down Expand Up @@ -58,11 +59,15 @@ the pipeline and names each step; read it there rather than here. It is the
copy a gate in abap2UI5 holds byte-identical to `frontend/common/README.md`,
which is why it is the one to trust — this file is not gated, and a third
description of the same mechanics is a third thing that can go quietly wrong.
A change to the README therefore starts in abap2UI5, in
`frontend/common/README.md`, and is applied here byte for byte.

What matters for working here, and is not in the README: `build/` in abap2UI5
is driven by [`tools/`](https://github.com/abap2UI5/abap2UI5/tree/main/tools),
the deploy stamps but does not build what it ships, and every published branch
is therefore exactly one commit ahead of `main`.
What matters for working here, and is not in the README: no delivery tree is
committed in abap2UI5. `frontend_check` builds every branch from the pull
request into its git-ignored `tools/out/`, `frontend_deploy` runs the same
build on `main` and stamps what it built, and the `result/<branch>` folders
here are the only durable copies — so every published branch is exactly one
commit ahead of `main`.

Besides the machine-written `result/` trees, `main` carries only the
repository's own face: README, CONTRIBUTING, AGENTS.md, CLAUDE.md, the issue
Expand All @@ -75,9 +80,41 @@ same system comes from the same workflow with a `standard_<name>` branch
(details in
[`tools/bsp_rename`](https://github.com/abap2UI5/abap2UI5/tree/main/tools/bsp_rename)).

## The embed control

The branches `standard_new` and `cloud_new` are the two kinds of branch this
repository publishes, told apart by what they carry:

| | `cloud`, `cloud_v2`, `standard`, `standard_v2` | `cloud_new`, `standard_new` |
|---|---|---|
| frontend code in the branch | a generated copy of abap2UI5's `app/webapp` | none |
| what the app is | the abap2UI5 frontend itself | one view with one `z2ui5.embed.Container`, filling the page |
| where the frontend comes from | the branch — pull it again after an abap2UI5 update | the backend, at runtime (`?z2ui5-bundle`) — nothing to pull after an update |
| source in abap2UI5 | `app/webapp` | [`frontend/embed`](https://github.com/abap2UI5/abap2UI5/tree/main/frontend/embed) |
| README of the branch | `frontend/common/README.md` (this repository's README, stamped) | `frontend/common/README_new.md` |

`z2ui5.embed.Container` is a custom control. It is **not** developed in
abap2UI5 and not in this repository: its source is
[abap2UI5/embed-control](https://github.com/abap2UI5/embed-control), it is
published as [`@abap2ui5/embed-control`](https://www.npmjs.com/package/@abap2ui5/embed-control),
and abap2UI5 pins one version of it in `frontend/embed/package.json` and in
its root `package.json` (the build fails when the two differ). A report about
the control goes there; a report about the frontend it loads goes to abap2UI5;
`frontend/embed` works around neither.

Both kinds of branch keep the deployment identity of `standard` and `cloud` —
the abapGit repository, every package and object, the ICF nodes, the BSP
`Z2UI5`, the launchpad component `z2ui5` with its inbound `z2ui5-display`,
the sibling BSPs `Z2UI5_CCI` and `Z2UI5_CCC` — so a system switches between
them by pulling another branch, in either direction. abap2UI5's
`tools/check-identity.mjs` holds every build to that; a change that breaks it
belongs nowhere, and a request to rename one of those objects for a `_new`
branch is declined with that reason.

## Validation

Nothing is built or linted here any more. abap2UI5's `frontend_check` builds
every branch variant and lints the generated ABAP on each pull request there —
including the BSP page invariants, against the webapp being changed. All text
files are LF-only.
including the BSP page invariants, against the webapp being changed, the
identity check above, and the tests of `frontend/embed`. All text files are
LF-only.
5 changes: 3 additions & 2 deletions CONTRIBUTING.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -18,7 +18,7 @@ What this page adds is the consequence, and it is the whole reason it exists:

| Content | Written by | A hand-made change here … |
|---|---|---|
| `result/` on `main` | abap2UI5's `frontend_deploy` workflow, which commits the trees committed in its `build/` | is overwritten on the next delivery |
| `result/` on `main` | abap2UI5's `frontend_deploy` workflow, which builds the trees on `main` there — the same build `frontend_check` ran on the pull request, into its git-ignored `tools/out/`; no tree is committed on that side | is overwritten on the next delivery |
| every generated branch | the `deliver` workflow, which rewrites each branch as one commit on top of `main` carrying its `result/<branch>` content | is discarded on the next delivery |

The failure is not loud. The change is reviewed, merged, and works — until an
Expand All @@ -39,7 +39,8 @@ branch can be exactly one commit ahead of it.
| You want to … | Go to |
|---|---|
| change the UI5 webapp | [abap2UI5/abap2UI5](https://github.com/abap2UI5/abap2UI5), directory `app/webapp/` — then run `npm run app2abap` there to regenerate `src/01/03`, and the build delivers it here |
| change the app of `standard_new` and `cloud_new` (the embed control app) | [abap2UI5/abap2UI5](https://github.com/abap2UI5/abap2UI5), directory [`frontend/embed/`](https://github.com/abap2UI5/abap2UI5/tree/main/frontend/embed) |
| change the app of `standard_new` and `cloud_new` (one view around the embed control) | [abap2UI5/abap2UI5](https://github.com/abap2UI5/abap2UI5), directory [`frontend/embed/`](https://github.com/abap2UI5/abap2UI5/tree/main/frontend/embed) — its rules are `frontend/embed/AGENTS.md` |
| change the embed control itself (`z2ui5.embed.Container`, what loads the frontend from the backend) | [abap2UI5/embed-control](https://github.com/abap2UI5/embed-control), published as [`@abap2ui5/embed-control`](https://www.npmjs.com/package/@abap2ui5/embed-control) — the `_new` branches pick up a new version when abap2UI5 bumps the pin in `frontend/embed/package.json` and its root `package.json` |
| change the ABAP handlers, the BSP packaging or the build | [abap2UI5/abap2UI5](https://github.com/abap2UI5/abap2UI5) — the ABAP artefacts and the files every branch inherits in [`frontend/`](https://github.com/abap2UI5/abap2UI5/tree/main/frontend), the scripts in [`tools/`](https://github.com/abap2UI5/abap2UI5/tree/main/tools) |
| report a bug or request a feature | [abap2UI5 issues](https://github.com/abap2UI5/abap2UI5/issues) |
| get the BSP under a different name | run abap2UI5's [`frontend_deploy` workflow](https://github.com/abap2UI5/abap2UI5/actions/workflows/frontend_deploy.yaml) with a `standard_<name>` branch — no code change needed, see [`tools/bsp_rename`](https://github.com/abap2UI5/abap2UI5/tree/main/tools/bsp_rename) |
Expand Down
15 changes: 9 additions & 6 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -12,11 +12,11 @@ This repository contains an abap2UI5 frontend artefacts service. For more inform
> ```
> abap2UI5/abap2UI5 abap2UI5/frontend
> frontend_deploy deliver
> app/webapp/ ──▶ build/ ──────────▶ main ──────────▶ cloud
> app/webapp/ ──▶ tools/out/ ──────▶ main ──────────▶ cloud
> (the webapp) (each branch result/<branch> cloud_v2
> + frontend/ as a committed (all six trees, standard
> tree) one commit per standard_v2
> change) cloud_new
> + frontend/ built at deploy (all six trees, standard
> abap, embed time, git-ignored, one commit per standard_v2
> never committed) change) cloud_new
> standard_new
> (each: main
> + one commit)
Expand All @@ -38,7 +38,7 @@ Every branch is generated in [abap2UI5](https://github.com/abap2UI5/abap2UI5)
| cloud_new | S/4 Public Cloud, BTP ABAP Environment | embed control | `npm run frontend:cloud_new` |
| standard_new | S/4 Private Cloud, S/4 On-Premise, R/3 NetWeaver >750 | embed control | `npm run frontend:standard_new` |

The `_new` branches carry no copy of the abap2UI5 frontend: their app is one view with one [`z2ui5.embed.Container`](https://www.npmjs.com/package/@abap2ui5/embed-control), which loads the frontend from the backend it runs against — an abap2UI5 update needs no frontend pull any more. Same objects, names, endpoints and launchpad settings as `cloud` and `standard` - a system switches between the branches by pulling another one, and launchpad target mappings and external links keep working (checked on every build by `tools/check-identity.mjs`); they need an abap2UI5 newer than 1.146.0. The app lives in [`frontend/embed`](https://github.com/abap2UI5/abap2UI5/tree/main/frontend/embed) of abap2UI5, and each of the two branches has a README of its own.
The `_new` branches carry no copy of the abap2UI5 frontend: their app is one view with one [`z2ui5.embed.Container`](https://www.npmjs.com/package/@abap2ui5/embed-control), a custom control that loads the frontend from the backend it runs against (`?z2ui5-bundle`) — the frontend always has the version of the backend it talks to, and an abap2UI5 update needs no frontend pull any more. Same objects, names, endpoints and launchpad settings as `cloud` and `standard` - a system switches between the branches by pulling another one, and launchpad target mappings and external links keep working (checked on every build by `tools/check-identity.mjs`); they need an abap2UI5 newer than 1.146.0. The app lives in [`frontend/embed`](https://github.com/abap2UI5/abap2UI5/tree/main/frontend/embed) of abap2UI5, the control is developed in [abap2UI5/embed-control](https://github.com/abap2UI5/embed-control) and published as `@abap2ui5/embed-control`, and each of the two branches has a README of its own.

`main` carries this repository's own docs plus the machine-written `result/` trees — it is not a source either: a hand edit to `result/` is overwritten by the next delivery.

Expand All @@ -51,9 +51,12 @@ Nothing in this repository is written by hand any more. A change made to a gener
| `result/` on `main` | [abap2UI5](https://github.com/abap2UI5/abap2UI5) — its `frontend_deploy` workflow commits the six finished trees, one commit per content change |
| every branch (`cloud`, `cloud_v2`, `standard`, `standard_v2`, `cloud_new`, `standard_new`) | the `deliver` workflow here — each branch is `main` plus one commit carrying its `result/<branch>` content |
| `standard_<name>` | [abap2UI5](https://github.com/abap2UI5/abap2UI5) — built on demand by a `frontend_deploy` dispatch and pushed straight onto the branch |
| the app of `cloud_new` and `standard_new` | [abap2UI5](https://github.com/abap2UI5/abap2UI5), [`frontend/embed`](https://github.com/abap2UI5/abap2UI5/tree/main/frontend/embed) — the control it holds is [abap2UI5/embed-control](https://github.com/abap2UI5/embed-control)'s, pinned as `@abap2ui5/embed-control` |
| this repository's docs (`main`) | here, as a maintenance pull request |

So a frontend change belongs in abap2UI5: edit `app/webapp` there, run `npm run app2abap` to regenerate the embedded ABAP resources under `src/01/03` and `npm run frontend:build` to regenerate the delivery trees under `build/`, and commit both with the change. The BSP packaging is checked in the same pull request, against the webapp being changed (`frontend_check`), and `frontend_deploy` delivers the committed trees into `result/` on `main` here, from where `deliver` fans them out into the branches.
So a frontend change belongs in abap2UI5: edit `app/webapp` there and run `npm run app2abap` to regenerate the embedded ABAP resources under `src/01/03`. No delivery tree is committed with it: `frontend_check` builds all six branches from the pull request into the git-ignored `tools/out/` and checks the BSP packaging against the webapp being changed, and `frontend_deploy` runs the same build on `main`, stamps the trees and delivers them into `result/` on `main` here, from where `deliver` fans them out into the branches. (`npm run frontend:build` is that build on your machine, `npm run frontend:verify` compares it with what is published here.)

The `_new` branches take the other route to the same place. Nothing of `app/webapp` is generated into them: their app in [`frontend/embed`](https://github.com/abap2UI5/abap2UI5/tree/main/frontend/embed) is one view with one `z2ui5.embed.Container`, and the control fetches the abap2UI5 frontend from the backend at runtime — so a change to the frontend reaches a system on these branches with the backend, without a delivery here. What *is* delivered is the app itself, the control at the version pinned in `frontend/embed/package.json` and in the root `package.json` of abap2UI5 (both, or the build fails), and the ABAP artefacts. The control is developed in [abap2UI5/embed-control](https://github.com/abap2UI5/embed-control) and published as [`@abap2ui5/embed-control`](https://www.npmjs.com/package/@abap2ui5/embed-control): a limitation of the control is fixed there, one of the frontend in `app/webapp`, and neither is worked around in the app.

Because the overwrite is not loud — the change is merged, works, and vanishes on some later unrelated run — the convention is enforced rather than trusted: the `guard` workflow fails **every** pull request opened here, and a change to this repository's own docs is unlocked by a maintainer applying the `maintenance` label.

Expand Down
Loading