# 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
```