🗽 Sync 2026-10-23 00:46:23

luci-theme-argon/docs/DEVELOPMENT.md

@@ -17,6 +17,10 @@ make package/luci-theme-argon/compile V=s
 
 Theme settings are included. Select the nested `compat/luci-app-argon-config` package under LuCI applications only when building the migration package. Existing translation names remain `luci-i18n-argon-config-*`.
 
+Firmware and GitHub Actions build scripts should stop cloning the old standalone `luci-app-argon-config` repository and deselect that plugin. The old `1.0-r20261008` plugin duplicates the configuration, RPC services, settings page and icons now owned by the theme, causing APK's `trying to overwrite ... owned by luci-theme-argon` errors. New firmware only needs the theme. If the old package name is required, use this repository's empty migration package and keep exactly one definition of that package in the build tree. After updating an existing build tree, run `make defconfig` and clean the old plugin's build outputs before rebuilding.
+
+The older `does not support ucode template precompilation` log line is LuCI's skip message, separate from the file conflict. This package disables precompilation and ships `.ut` source to avoid SDK/target ucode bytecode incompatibilities; other LuCI packages can retain precompilation.
+
 Release CI builds IPK with the OpenWrt 23.05.5 SDK and APK v3 with the 25.12.5 SDK. Ucode templates ship as source to avoid tying packages to one runtime's bytecode format.
 
 Translations use `PKG_PO_VERSION` to follow the theme release, including `-r<revision>` for APK. IPK translations retain a `v` prefix (for example, `v3.0.1`) so ordinary installation upgrades the broken v3.0.0 `unknown` version. Keep that prefix in future IPK releases. CI reads each translation's internal package metadata and blocks artifact upload and publication if the version is wrong.
@@ -87,6 +91,46 @@ Top-level menu nodes resolve `htdocs/luci-static/argon/icon/<node-name>.svg`, in
 
 Use monochrome SVGs with a `viewBox` and transparent background. CSS masks supply theme and interaction colors. Shared chevrons use the same 24×24 grid and 2px round strokes. See the [icon index](../htdocs/luci-static/argon/icon/README.md) for available assets. This mechanism is separate from uploaded browser icons and login logos.
 
+## Static update feed deployment
+
+The router reads a static `/updates/stable.json` manifest without calling the GitHub API. After publication, CI uses its own `GITHUB_TOKEN` to retrieve the official release, verifies the theme package SHA256 digests and sizes, and generates one artifact. GitHub Pages publishes that artifact directly; Cloudflare Pages deploys the same files from a dedicated `updates` Git branch. Packages continue to download from the pinned GitHub Release, and translation packages remain separate.
+
+Initial maintainer setup:
+
+1. Set **Settings → Pages → Build and deployment → Source** to **GitHub Actions**. Allow the default branch and release tags in the `github-pages` environment. The workflow needs `contents: write` to publish the `updates` branch.
+2. Once this code is on the default branch, manually run **Publish update feeds**. This initializes GitHub Pages and creates the `updates` branch from the latest stable release, without publishing a new version or requiring CF setup first.
+3. Create a Cloudflare Pages **Git integration** project connected to this GitHub repository. Set production branch to `updates`, framework to **None**, build command to `exit 0`, output directory to `.`, and preview branches to **None**. Use the assigned `pages.dev` hostname or your own domain. Existing Direct Upload projects need to be replaced with a new Git integration project.
+4. Set these repository **Variables** under **Settings → Secrets and variables → Actions**:
+
+   | Variable | Value |
+   | --- | --- |
+   | `ARGON_UPDATE_PRIMARY_URL` | Complete URL, e.g. `https://<assigned-hostname>/updates/stable.json` |
+   | `ARGON_UPDATES_ENABLED` | `true` to synchronize after stable releases |
+   | `ARGON_UPDATE_FALLBACK_URL` | Optional; defaults to `https://jerrykuku.github.io/luci-theme-argon/updates/stable.json`. Override for a custom fallback domain. |
+
+5. Choose how CF is triggered. By default, keep automatic production branch deployments enabled: pushing `updates` triggers CF without a CF secret in GitHub. For Deploy Hooks, create a hook bound to `updates` under CF **Settings → Builds → Add deploy hook**. Save the complete URL as the GitHub repository Actions **Secret** `CF_PAGES_DEPLOY_HOOK`, then disable **Enable automatic production branch deployments** to avoid building each publication twice.
+6. Compare `/updates/stable.json` on both hosts byte for byte. Verify primary access, fallback access and actual package downloads from the target router's network. New release packages embed the configured source URLs; changing repository variables does not change themes already installed on devices.
+
+`CLOUDFLARE_API_TOKEN`, `CLOUDFLARE_ACCOUNT_ID` and `CLOUDFLARE_PAGES_PROJECT` are no longer used. The Hook URL contains its own trigger credential and belongs in a Secret. A successful Hook response means CF accepted the build request; check Pages for the actual deployment result.
+
+Only successful stable publications update the feed. Previews are excluded, and a delayed old-release job skips publication when its tag is no longer Latest. The `updates` branch contains generated static files, preserves commit history and rejects conflicting pushes. The publisher refuses to overwrite an existing unrelated branch with that name.
+
+Run **Publish update feeds** again to republish GitHub Pages. Identical artifacts do not create another branch commit. With a Hook configured, reruns still trigger CF when the branch is unchanged, allowing failed deployments to be retried. With Git auto-deployment only, retry the build in CF or publish changed feed content. Both publication jobs are independent, so either side can publish if the other fails.
+
+The manifest contains `schema`, `repository`, `tag`, `published_at`, `notes`, and the `apk`/`ipk` filenames with `_sha256`/`_size` fields. Metadata comes from the published package bytes rather than master's Makefile. Both formats must be complete and match the tag. Malformed feeds trigger fallback and never overwrite the previous successful cache. Checks are manual, with a five-minute success cache, a one-minute failure cooldown and a lock that coalesces concurrent requests.
+
+Source builds default to an empty CF primary. Configure one before packaging:
+
+```sh
+python3 .github/scripts/generate_update_site.py sources \
+  --primary 'https://YOUR_DOMAIN/updates/stable.json' \
+  --output root/usr/share/argon/update-sources.json
+```
+
+Sources must be complete HTTPS URLs without credentials, ports, query strings or fragments. Runtime sources live in `/usr/share/argon/update-sources.json`, which is updated by theme packages separately from `/etc/config/argon`. The installer constructs fixed official release download URLs; manifests cannot supply arbitrary download URLs.
+
+References: [Cloudflare GitHub integration](https://developers.cloudflare.com/pages/configuration/git-integration/github-integration/), [Deploy Hooks](https://developers.cloudflare.com/pages/configuration/deploy-hooks/), [branch deployment controls](https://developers.cloudflare.com/pages/configuration/branch-build-controls/), [custom GitHub Pages workflows](https://docs.github.com/en/pages/getting-started-with-github-pages/using-custom-workflows-with-github-pages).
+
 ## Checks
 
 Use Node.js 22+, Python 3, LESS 4.1.3 and a Ucode build matching the supported OpenWrt runtime: