Merge pull request #121 from abap2UI5/claude/article-info-page-renaming-3g8vk0

Expand downporting and renaming documentation with practical guides

Author: oblomov-dev

docs/.vitepress/config.mjs

@@ -342,7 +342,6 @@ export default defineConfig({
           { text: "Add-ons", link: "/advanced/addons" },
           { text: "Downporting", link: "/advanced/downporting" },
           { text: "Renaming", link: "/advanced/renaming" },
-          { text: "Build Process", link: "/advanced/builds" },
           { text: "Local Setup", link: "/advanced/local" },
           { text: "RFC Connector", link: "/advanced/rfc" },
           { text: "HTTP Connector", link: "/advanced/http" },

docs/advanced/builds.md

@@ -14,6 +14,15 @@ To install on an older system, use the `702` branch:
 
 Some sample projects and other repositories also ship a downported version. Check whether a `702` branch is available.
 
+#### Installation
+The installation on an old release follows the normal [installation](/configuration/installation) flow with two adjustments:
+1. Pull the `702` branch with abapGit — abapGit itself is 7.02-compatible, so deployment to old ECC machines works the same way as everywhere else
+2. Create the HTTP handler (SICF service) with the 7.02-compatible handler syntax instead of the modern snippet
+
+After that, call your HTTP handler from the browser and abap2UI5 is ready for use — even on your old machine.
+
+If you later want to reach these apps from the cloud, use the [RFC Connector](/advanced/rfc): it calls abap2UI5 apps on legacy systems via BTP destination and RFC, integrating them into Steampunk, S/4 Public Cloud, Fiori Launchpads, or SAP Mobile Start. The [HTTP Connector](/advanced/http) offers the same over HTTP.
+
 #### How It Works
 The `702` branch is not maintained by hand — it is **generated** from `main` by an automated GitHub Actions workflow on every change. The pipeline runs [abaplint](https://abaplint.org)'s downport rule (`abaplint --fix` with a 7.02 target configuration), which rewrites modern syntax into 7.02-compatible equivalents, for example:
 
@@ -22,9 +31,22 @@ The `702` branch is not maintained by hand — it is **generated** from `main` b
 - `xsdbool( )` → `boolc( )`
 - string templates → concatenation where needed
 
-A few small compatibility fix-ups follow (e.g. replacing exception types that don't exist on old releases), and the result is committed to the `702` branch. Because the transformation is fully automatic, the downported version stays feature-identical with `main` — you never wait for a manual backport.
+A few small compatibility fix-ups follow (e.g. replacing exception types that don't exist on old releases), and the result is committed to the `702` branch. Because the transformation is fully automatic, the downported version stays feature-identical with `main` — you never wait for a manual backport. And since the main code line stays on 7.50 syntax, contributors write and debug modern ABAP instead of 7.02 syntax.
 
 The same mechanism runs in this project's CI (`npm run auto_downport`) to guarantee every change on `main` stays downportable.
 
+#### Why abap2UI5 Is Downportable
+Automatic syntax rewriting is only the last step. The codebase is compatible with everything from ABAP 7.02 up to the newest ABAP Cloud because of four design principles:
+
+**1. Only basic technology.** No OData services, CDS views, or new EML syntax — none of these exist on older ECCs. Conversely, no SAP GUI or other statements forbidden in ABAP Cloud. The only universally available technology is a plain HTTP service (defined via SICF on-premise, via Eclipse in the cloud), and that is all abap2UI5 needs for communication.
+
+**2. Few SAP dependencies.** SAP APIs like `/UI2/CL_JSON` or function modules may be missing or behave differently on certain releases, and their availability per release is poorly documented. abap2UI5 therefore replaces SAP dependencies with open-source projects where possible — most importantly [ajson](/technical/tools/ajson) for JSON handling, which is compatible from 7.02 to ABAP Cloud and ships bundled under the `z2ui5` namespace. Browse [dotabap.org](https://dotabap.org) for more open-source projects that can reduce your own dependencies.
+
+**3. Version-independent code.** Where a dependency is unavoidable and SAP offers different APIs per language version (e.g., generating UUIDs), abap2UI5 uses a hybrid approach: dynamic ABAP calls the new API in ABAP for Cloud and falls back to the classic API in Standard ABAP — one code line, no syntax errors on either side. Not always elegant, but very pragmatic.
+
+**4. Downported syntax.** The main code line is written in 7.50 syntax and the `702` branch is generated automatically, as described above.
+
+Keep these principles in mind if you want to set up your next abapGit project with compatibility for older releases.
+
 #### Further Reading
 Background article: [Running abap2UI5 on older R/3 Releases](https://www.linkedin.com/pulse/running-abap2ui5-older-r3-releases-downport-compatibility-abaplint-mjkle).

docs/advanced/downporting.md

@@ -7,9 +7,15 @@ The entire abap2UI5 project lives under the `z2ui5` namespace. You may need to r
 - Different modules, e.g., `z2ui5_sd`, `z2ui5_mm`
 - Custom namespaces, e.g., `/ZZZ/`, `/YYY/`
 - Release-specific naming, e.g., `z2411`, `z2502`
+- One installation per app, e.g., `z2ui5app1`, `z2ui5app2`
 
 abap2UI5 works with the abaplint renaming feature and supports namespaces up to 9 characters, e.g., `zabap2ui5`.
 
+#### Why Rename?
+ABAP stacks have no package manager: every object pulled with abapGit is created globally, so a system can hold only one version of abap2UI5 — and every app in the system is forced to use it. Pulling the latest version can then break existing apps. Public API changes are kept to a minimum, but a constantly evolving project cannot avoid them entirely.
+
+Renaming closes this gap. It is not a true package management system, but it lets you install abap2UI5 multiple times under different namespaces in the same system and upgrade each installation at its own pace. At the app level, you simply implement the renamed app interface — e.g., `z2ui5_sd_if_app` or `z2411_if_app` instead of `z2ui5_if_app`.
+
 #### How It Works
 [abaplint](https://abaplint.org) can rename ABAP artifacts across a whole repository: you define rename patterns (old name → new name, including regular expressions) in an abaplint configuration, and `abaplint --rename` rewrites every class, interface, and reference consistently, writing the result to an output folder:
 
@@ -24,7 +30,19 @@ abap2UI5 works with the abaplint renaming feature and supports namespaces up to
 
 The renamed copy is a complete, installable abapGit project under your own namespace — install it side by side with the original, pin it to a release, or ship it inside your product. The abap2UI5 CI runs this transformation on every change (`npm run rename`, workflow `test_rename.yaml`) to guarantee the codebase stays renameable.
 
-For a ready-made pipeline that builds a renamed release with your chosen add-ons included, see the [Builder](/advanced/builds).
+#### Step-by-Step Guide
+The [abap2UI5-renamed](https://github.com/abap2UI5/abap2UI5-renamed) repository shows the full setup: a GitHub Action runs `abaplint abaplint_rename.json --rename` and commits the renamed artifacts back via pull request. Use it as a template for your own renaming repository:
+
+1. **Fork** the [renaming repository](https://github.com/abap2UI5/abap2UI5-renamed)
+2. **Configure your namespace** in `abaplint_rename.json` — set the old and new names in the rename patterns
+3. **Run the GitHub Action** — open the Actions tab, enable workflows, and start the renaming job
+4. **Merge the pull request** the job creates; your repository now contains all abap2UI5 artifacts under the new namespace
+5. **Install with abapGit** — pull the renamed repository into your ABAP system
+
+That's it — abap2UI5 now runs under your custom namespace, side by side with any other installation. Consider extending the GitHub Action to automate the process even further, e.g., pulling a fresh release on a regular schedule.
+
+#### Renaming in Practice: ajson
+abap2UI5 itself relies on this feature: its JSON handling comes from the open-source project [ajson](https://github.com/sbcgua/ajson), which is integrated under the `z2ui5` namespace via renaming — so there are no collisions if you pull both abap2UI5 and ajson separately into the same system. A GitHub Action in the [mirror-ajson](https://github.com/abap2UI5/mirror-ajson) repository checks weekly for upstream changes and automatically creates a pull request with the latest ajson version renamed to `z2ui5`. abapGit bundles ajson under its own namespace the same way — renaming with abaplint also makes it possible to integrate open-source projects into each other.
 
 #### Further Reading
 - [Automagic standalone renaming of ABAP objects](https://community.sap.com/t5/application-development-blog-posts/automagic-standalone-renaming-of-abap-objects/ba-p/13499851)