convertor/.github/UPSTREAM_SYNC.md

🔄 Upstream 自動同步機制

本專案實作了完整的 upstream 自動同步、變更追蹤與 smoke test 機制。

📋 目錄

• 功能概述
• 工作流程圖
• Workflow 說明
• Smoke Test 內容
• 設定說明
• 手動操作

---

功能概述

1️⃣ 自動同步 Upstream

功能	說明
觸發方式	每 6 小時自動檢查 / 手動觸發
同步目標	dev 分支
Merge 策略	自動 merge（無衝突時）
衝突處理	自動建立 GitHub Issue 通知

2️⃣ 變更摘要

同步完成後自動產生：

• ✅ GitHub Issue（詳細變更記錄）
• ✅ upstream-changelog.md（累積變更歷史）
• ✅ GitHub Actions Summary（快速查看）

3️⃣ Smoke Test

測試項目	內容	時間限制
Container 啟動	驗證 image 可正常啟動	60s
工具檢查	libreoffice, pandoc, ffmpeg, tesseract	30s
最小轉換	txt → pdf	60s
API 端點	healthcheck, root	10s
總計		< 10 分鐘

---

工作流程圖

┌─────────────────────────────────────────────────────────────────────────┐
│                         Upstream 自動同步流程                              │
└─────────────────────────────────────────────────────────────────────────┘

    ┌──────────────┐
    │   Upstream   │
    │  (C4illin/   │
    │  ConvertX)   │
    └──────┬───────┘
           │
           │ 每 6 小時檢查
           ▼
    ┌──────────────┐     無更新      ┌──────────────┐
    │  檢查是否有   │ ─────────────► │   結束       │
    │  新 commits  │                 └──────────────┘
    └──────┬───────┘
           │ 有更新
           ▼
    ┌──────────────┐     衝突        ┌──────────────┐
    │  自動 Merge  │ ─────────────► │ 建立 Issue   │
    │  到 dev 分支  │                │ 需手動處理    │
    └──────┬───────┘                └──────────────┘
           │ 成功
           ▼
    ┌──────────────┐
    │  產生變更摘要  │
    │  • Issue     │
    │  • Changelog │
    └──────┬───────┘
           │
           ▼
    ┌──────────────┐
    │  Push 到 dev │
    └──────┬───────┘
           │
           │ 觸發 upstream-sync.yml
           ▼
    ┌──────────────┐
    │  Build 測試  │
    │  Image (amd64)│
    └──────┬───────┘
           │
           ▼
    ┌──────────────────────────────────────────────────┐
    │                  Smoke Test                       │
    │  ┌────────────┐ ┌────────────┐ ┌────────────┐   │
    │  │ Container  │ │   工具     │ │   轉換     │   │
    │  │   啟動     │ │   檢查     │ │   測試     │   │
    │  └─────┬──────┘ └─────┬──────┘ └─────┬──────┘   │
    │        │              │              │           │
    │        └──────────────┼──────────────┘           │
    │                       │                          │
    └───────────────────────┼──────────────────────────┘
                            │
              ┌─────────────┴─────────────┐
              │                           │
              ▼                           ▼
       ┌────────────┐              ┌────────────┐
       │  ✅ 通過   │              │  ❌ 失敗   │
       └─────┬──────┘              └─────┬──────┘
             │                           │
             ▼                           ▼
       ┌────────────┐              ┌────────────┐
       │ Build 並   │              │ Workflow   │
       │ Push 到    │              │ 失敗       │
       │ Docker Hub │              │ (不發布)    │
       └─────┬──────┘              └────────────┘
             │
             ▼
       ┌────────────────────────┐
       │ upstream-YYYYMMDD tag  │
       │ ❌ 不更新 latest        │
       │ ❌ 不打 semver tag      │
       └────────────────────────┘

---

Workflow 說明

auto-upstream-sync.yml

用途： 自動檢測並同步 upstream 更新

觸發條件：

• ⏰ 每 6 小時自動執行
• 🖱️ 手動觸發

主要步驟：

1. Fetch upstream 最新程式碼
2. 檢查是否有新 commits
3. 自動 merge 到 dev 分支
4. 產生變更摘要（Issue + Changelog）
5. Push 到 dev

upstream-sync.yml

用途： 當 dev 分支有 push 時，執行 build + smoke test

觸發條件：

• 📦 dev 分支有 push

主要步驟：

1. Build 測試用 image（僅 amd64，加速測試）
2. 執行 Smoke Test（10 分鐘內）
3. 測試通過後 build multi-arch image
4. Push 到 Docker Hub（tag: upstream-YYYYMMDD）

---

Smoke Test 內容

Test 1: Container 啟動測試

# 啟動 container 並等待 healthcheck 回應
docker run -d --name convertx-test $IMAGE
curl http://localhost:3000/healthcheck

Test 2: 關鍵工具檢查

# 必須通過（任一失敗則整體失敗）
libreoffice --version
pandoc --version
ffmpeg -version
tesseract --version

Test 3: 最小轉換測試

# txt → pdf 轉換測試
echo "test" > test.txt
libreoffice --headless --convert-to pdf test.txt

Test 4: API 端點檢查

# 確認服務正常運作
curl http://localhost:3000/healthcheck
curl http://localhost:3000/

---

設定說明

必要的 GitHub Secrets

在 Repository Settings → Secrets and variables → Actions 中設定：

Secret 名稱	說明
DOCKERHUB_USERNAME	Docker Hub 帳號
DOCKERHUB_TOKEN	Docker Hub Access Token

分支保護規則

建議設定：

main 分支：

• ✅ Require pull request before merging
• ✅ Require status checks to pass
• ❌ Allow force pushes

dev 分支：

• ✅ Allow direct pushes (for automation)

---

手動操作

手動觸發同步

1. 前往 Actions → Auto Upstream Sync
2. 點選 "Run workflow"
3. 可選擇「強制同步」

手動處理 Merge 衝突

當自動同步發生衝突時：

# 1. 切換到 dev 分支
git checkout dev

# 2. 添加 upstream remote（如果還沒有）
git remote add upstream https://github.com/C4illin/ConvertX.git

# 3. Fetch upstream
git fetch upstream main

# 4. Merge upstream
git merge upstream/main

# 5. 解決衝突
# ... 編輯衝突的檔案 ...

# 6. 提交並 push
git add .
git commit -m "Resolve merge conflicts with upstream"
git push origin dev

---

⚠️ 注意事項

1. 不會自動更新 latest tag - 需要手動發布正式版本
2. 不會自動打 semver tag - 需要手動建立 release
3. main 分支不會被自動修改 - 只有 dev 會自動同步
4. Smoke test 失敗時不會發布 image - 確保品質

---

📊 Docker Image Tag 規則

Tag 格式	說明	自動/手動
upstream-YYYYMMDD	Upstream 同步版（經過 smoke test）	自動
vX.Y.Z	正式版本	手動
latest	最新穩定版	手動