diff --git a/.github/pull_request_template.md b/.github/pull_request_template.md index f96a164..7bacb2a 100644 --- a/.github/pull_request_template.md +++ b/.github/pull_request_template.md @@ -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. diff --git a/.github/workflows/deliver.yaml b/.github/workflows/deliver.yaml index 4991d62..aa56784 100644 --- a/.github/workflows/deliver.yaml +++ b/.github/workflows/deliver.yaml @@ -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/), and its frontend_deploy workflow writes the -# stamped result as result/ 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/ +# 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/, nothing else diff --git a/.github/workflows/guard.yaml b/.github/workflows/guard.yaml index fd6bab4..79a2c7e 100644 --- a/.github/workflows/guard.yaml +++ b/.github/workflows/guard.yaml @@ -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" diff --git a/AGENTS.md b/AGENTS.md index cf3d1a3..a8db80c 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -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 @@ -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 @@ -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/` on `main` here, and the `deliver` workflow rewrites each - branch as one commit on top of `main` carrying its folder's content; - `standard_` 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/` on `main` here, and the + `deliver` workflow rewrites each branch as one commit on top of `main` + carrying its folder's content; `standard_` 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 @@ -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/` 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 @@ -75,9 +80,41 @@ same system comes from the same workflow with a `standard_` 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. diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 8080ed6..7d4376f 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -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/` content | is discarded on the next delivery | The failure is not loud. The change is reviewed, merged, and works — until an @@ -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_` branch — no code change needed, see [`tools/bsp_rename`](https://github.com/abap2UI5/abap2UI5/tree/main/tools/bsp_rename) | diff --git a/README.md b/README.md index a043ca4..6044263 100644 --- a/README.md +++ b/README.md @@ -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/ 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) @@ -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. @@ -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/` content | | `standard_` | [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.