refactor: upstream sync strategy with dynamic GENERAL.txt

2026-03-01 14:03:58 +08:00
parent 6ee3e2f832
commit a54452915d
9 changed files with 213 additions and 52 deletions
--- a/docs/SKILLS.md
+++ b/docs/SKILLS.md
@@ -0,0 +1,115 @@
+# OpenWrt/ImmortalWrt IPQ60XX — Woodpecker Build Skills
+
+## Repo role
+This repo is a build-orchestration repo (configs + scripts + woodpecker pipeline).
+Upstream source is cloned during CI.
+
+## Upstream config sync strategy
+
+### Three-layer upstream model
+
+1. **SOURCE 上游（固件源码）**
+   - `WRT_REPO = https://github.com/VIKINGYFY/immortalwrt.git`
+   - `WRT_BRANCH = main`
+
+2. **CI-TEMPLATE 上游（配置/脚本参考）**
+   - 设备集（固定）：
+     - VIKINGYFY/OpenWRT-CI: `Config/IPQ60XX-WIFI-YES.txt`
+     - davidtall/OpenWRT-CI: `Config/IPQ60XX-WIFI.txt`
+   - 通用包（动态拉取）：
+     - `Config/GENERAL.upstream.txt` 编译时从 davidtall/OpenWRT-CI 下载
+
+3. **YOUR-DELTA（你自己的增量，永远只改这里）**
+   - `Config/GENERAL.local.txt` - 你的包/功能增量
+   - `Scripts/Packages.sh` - 需要固定仓库版本的第三方包/去冲突
+   - `Scripts/Handles.sh` - 脚本辅助函数
+   - `Scripts/Settings.sh` - kconfig 设置调整
+   - `files/` - 固件内默认配置覆盖
+
+## How config merging works
+
+During build, `.config` is assembled from THREE files in this order:
+
+```
+cat Config/IPQ60XX-WIFI-*.txt \
+    Config/GENERAL.upstream.txt \
+    Config/GENERAL.local.txt > .config
+```
+
+Later entries override earlier ones, so:
+- Device set config < Upstream GENERAL
+- Upstream GENERAL < Your local overrides
+
+## Where to add your packages
+
+### 1) If package exists in feeds
+Simply append `CONFIG_PACKAGE_xxx=y` to `Config/GENERAL.local.txt`
+
+Example:
+```
+CONFIG_PACKAGE_luci-app-adguardhome=y
+CONFIG_PACKAGE_luci-app-wireguard=y
+```
+
+### 2) If package is not in feeds / you need pinned repo
+Add clone/remove conflict logic in `Scripts/Packages.sh`
+This runs after feeds, before defconfig.
+
+Example:
+```bash
+# Clone a custom package repo
+git clone --depth=1 https://github.com/user/package.git package/custom-package
+
+# Remove conflicting packages
+rm -rf package/conflicting-package
+```
+
+## Fixing build issues with upstream changes
+
+If upstream GENERAL.txt breaks your build:
+
+### Quick fix (pin to a known good commit)
+Set `UPSTREAM_GENERAL_REF` in Woodpecker variables to a specific commit hash:
+```
+UPSTREAM_GENERAL_REF=abc123def456
+```
+
+### Permanent fix
+Override the problematic config in `Config/GENERAL.local.txt`
+
+## Woodpecker cron builds
+
+Create a cron job in Woodpecker UI for this repo:
+1. Go to Repository Settings > Schedules
+2. Add new schedule (e.g., daily at 03:00)
+3. Pipeline runs automatically on `event: cron`
+
+## Debugging
+
+To test config merging locally:
+```bash
+./Scripts/sync_upstream_config.sh
+cat Config/IPQ60XX-WIFI-YES.txt Config/GENERAL.upstream.txt Config/GENERAL.local.txt > test.config
+```
+
+## File structure
+
+```
+.
+├── .woodpecker/
+│   └── ipq60xx.yml          # Woodpecker pipeline
+├── Config/
+│   ├── IPQ60XX-WIFI-YES.txt # Device set A (static)
+│   ├── IPQ60XX-WIFI.txt     # Device set B (static)
+│   ├── GENERAL.local.txt    # YOUR overrides (edit this!)
+│   └── GENERAL.upstream.txt # Fetched at build time (DO NOT EDIT)
+├── Scripts/
+│   ├── sync_upstream_config.sh  # Pull GENERAL.txt from upstream
+│   ├── Packages.sh              # Package injection (edit as needed)
+│   ├── Handles.sh               # Helper functions
+│   └── Settings.sh               # kconfig tweaks
+├── files/                     # Rootfs overlay (optional)
+├── artifacts/                  # Build outputs (gitignored)
+└── docs/
+    └── SKILLS.md               # This file
+```