diff --git a/.github/actions/setup-ng2/action.yml b/.github/actions/setup-ng2/action.yml new file mode 100644 index 00000000..1e41f3aa --- /dev/null +++ b/.github/actions/setup-ng2/action.yml @@ -0,0 +1,88 @@ +name: Set up NG2 dependencies +description: Install Homebrew tools and optionally fetch verified external binaries. +inputs: + packages: + description: Space-separated Homebrew formulae to install. + default: age go-task xcodegen swiftlint + external-binaries: + description: Whether to fetch and verify external binaries. + default: 'true' +runs: + using: composite + steps: + - name: Prepare Homebrew download cache + shell: bash + env: + HOMEBREW_PACKAGES: ${{ inputs.packages }} + id: homebrew-cache-key + run: | + read -r -a packages <<< "$HOMEBREW_PACKAGES" + brew info --json=v2 "${packages[@]}" > "$RUNNER_TEMP/homebrew-formulae.json" + formula_hash=$(python3 - "$RUNNER_TEMP/homebrew-formulae.json" <<'PY' + import hashlib + import json + import sys + + with open(sys.argv[1]) as source: + formulae = json.load(source)["formulae"] + versions = sorted( + (f["full_name"], f["versions"]["stable"], f["revision"], f["bottle"]) + for f in formulae + ) + print(hashlib.sha256(json.dumps(versions, sort_keys=True).encode()).hexdigest()) + PY + ) + echo "path=$(brew --cache)/downloads" >> "$GITHUB_OUTPUT" + echo "key=ng2-homebrew-downloads-v1-macos-$(sw_vers -productVersion)-$(uname -m)-$formula_hash" >> "$GITHUB_OUTPUT" + + - name: Restore Homebrew download cache + id: homebrew-cache + uses: actions/cache/restore@55cc8345863c7cc4c66a329aec7e433d2d1c52a9 # v6.1.0 + with: + path: ${{ steps.homebrew-cache-key.outputs.path }} + key: ${{ steps.homebrew-cache-key.outputs.key }} + + - name: Install build tools and test dependencies + id: install-build-tools + shell: bash + env: + HOMEBREW_PACKAGES: ${{ inputs.packages }} + HOMEBREW_NO_AUTO_UPDATE: '1' + HOMEBREW_NO_INSTALL_CLEANUP: '1' + run: | + read -r -a packages <<< "$HOMEBREW_PACKAGES" + brew install "${packages[@]}" + + - name: Save Homebrew download cache + if: steps.install-build-tools.outcome == 'success' && steps.homebrew-cache.outputs.cache-hit != 'true' + uses: actions/cache/save@55cc8345863c7cc4c66a329aec7e433d2d1c52a9 # v6.1.0 + with: + path: ${{ steps.homebrew-cache-key.outputs.path }} + key: ${{ steps.homebrew-cache.outputs.cache-primary-key }} + + - name: Restore external binary archive cache + if: inputs.external-binaries == 'true' + id: external-binary-cache + uses: actions/cache/restore@55cc8345863c7cc4c66a329aec7e433d2d1c52a9 # v6.1.0 + with: + path: ShadowsocksX-NG2/.build/external-binary-archives + key: ng2-external-binaries-macos-arm64-${{ hashFiles('ShadowsocksX-NG2/Vendor/*/manifest.json') }} + restore-keys: | + ng2-external-binaries-macos-arm64- + + - name: Fetch and verify external binaries + if: inputs.external-binaries == 'true' + shell: bash + id: fetch-external-binaries + working-directory: ShadowsocksX-NG2 + env: + EXTERNAL_BINARY_CACHE_DIR: ${{ github.workspace }}/ShadowsocksX-NG2/.build/external-binary-archives + run: Scripts/fetch-external-binaries.sh + + - name: Save external binary archive cache + if: inputs.external-binaries == 'true' && steps.fetch-external-binaries.outcome == 'success' && steps.external-binary-cache.outputs.cache-hit != 'true' + uses: actions/cache/save@55cc8345863c7cc4c66a329aec7e433d2d1c52a9 # v6.1.0 + with: + path: ShadowsocksX-NG2/.build/external-binary-archives + key: ${{ steps.external-binary-cache.outputs.cache-primary-key }} + diff --git a/.github/workflows/shadowsocksx-ng2-ci.yml b/.github/workflows/shadowsocksx-ng2-ci.yml index 69e1a560..dfaddfca 100644 --- a/.github/workflows/shadowsocksx-ng2-ci.yml +++ b/.github/workflows/shadowsocksx-ng2-ci.yml @@ -14,111 +14,93 @@ concurrency: group: ng2-ci-${{ github.workflow }}-${{ github.event.pull_request.number || github.ref }} cancel-in-progress: true +defaults: + run: + working-directory: ShadowsocksX-NG2 + jobs: - checks: - name: ${{ matrix.gate == 'test' && 'Lint, test, build' || 'Smoke tests' }} (Xcode 27 arm64) - strategy: - fail-fast: false - matrix: - gate: [test, 'test:smoke'] + style: + name: Style (Xcode 27 arm64) runs-on: xcode-27 timeout-minutes: 60 - steps: - name: Check out source uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1 with: persist-credentials: false - - name: Prepare Homebrew download cache - id: homebrew-cache-key - run: | - brew info --json=v2 age go-task xcodegen swiftlint > "$RUNNER_TEMP/homebrew-formulae.json" - formula_hash=$(python3 - "$RUNNER_TEMP/homebrew-formulae.json" <<'PY' - import hashlib - import json - import sys - - with open(sys.argv[1]) as source: - formulae = json.load(source)["formulae"] - versions = sorted( - (f["full_name"], f["versions"]["stable"], f["revision"], f["bottle"]) - for f in formulae - ) - print(hashlib.sha256(json.dumps(versions, sort_keys=True).encode()).hexdigest()) - PY - ) - echo "path=$(brew --cache)/downloads" >> "$GITHUB_OUTPUT" - echo "key=ng2-homebrew-downloads-v1-macos-$(sw_vers -productVersion)-$(uname -m)-$formula_hash" >> "$GITHUB_OUTPUT" - - - name: Restore Homebrew download cache - id: homebrew-cache - uses: actions/cache/restore@55cc8345863c7cc4c66a329aec7e433d2d1c52a9 # v6.1.0 + - name: Set up dependencies + uses: ./.github/actions/setup-ng2 with: - path: ${{ steps.homebrew-cache-key.outputs.path }} - key: ${{ steps.homebrew-cache-key.outputs.key }} - - - name: Install build tools and test dependencies - id: install-build-tools - env: - HOMEBREW_NO_AUTO_UPDATE: '1' - HOMEBREW_NO_INSTALL_CLEANUP: '1' - run: brew install age go-task xcodegen swiftlint - - - name: Save Homebrew download cache - if: steps.install-build-tools.outcome == 'success' && steps.homebrew-cache.outputs.cache-hit != 'true' - uses: actions/cache/save@55cc8345863c7cc4c66a329aec7e433d2d1c52a9 # v6.1.0 - with: - path: ${{ steps.homebrew-cache-key.outputs.path }} - key: ${{ steps.homebrew-cache-key.outputs.key }} - - - name: Restore external binary archive cache - id: external-binary-cache - uses: actions/cache/restore@55cc8345863c7cc4c66a329aec7e433d2d1c52a9 # v6.1.0 - with: - path: ShadowsocksX-NG2/.build/external-binary-archives - key: ng2-external-binaries-macos-arm64-${{ hashFiles('ShadowsocksX-NG2/Vendor/sslocal/manifest.json', 'ShadowsocksX-NG2/Vendor/v2ray-plugin/manifest.json', 'ShadowsocksX-NG2/Vendor/ck-client/manifest.json') }} - restore-keys: | - ng2-external-binaries-macos-arm64- - - - name: Fetch and verify external binaries - id: fetch-external-binaries - working-directory: ShadowsocksX-NG2 - env: - EXTERNAL_BINARY_CACHE_DIR: ${{ github.workspace }}/ShadowsocksX-NG2/.build/external-binary-archives - run: Scripts/fetch-external-binaries.sh - - - name: Save external binary archive cache - if: steps.fetch-external-binaries.outcome == 'success' && steps.external-binary-cache.outputs.cache-hit != 'true' - uses: actions/cache/save@55cc8345863c7cc4c66a329aec7e433d2d1c52a9 # v6.1.0 - with: - path: ShadowsocksX-NG2/.build/external-binary-archives - key: ng2-external-binaries-macos-arm64-${{ hashFiles('ShadowsocksX-NG2/Vendor/sslocal/manifest.json', 'ShadowsocksX-NG2/Vendor/v2ray-plugin/manifest.json', 'ShadowsocksX-NG2/Vendor/ck-client/manifest.json') }} + packages: go-task swiftlint + external-binaries: 'false' - name: Check Swift formatting - if: matrix.gate == 'test' - working-directory: ShadowsocksX-NG2 - run: task format:check + run: task --exit-code validate -- format:check - name: Lint - if: matrix.gate == 'test' - working-directory: ShadowsocksX-NG2 - run: task --exit-code lint + run: task --exit-code validate -- lint - - name: Test - working-directory: ShadowsocksX-NG2 - run: task --exit-code validate -- ${{ matrix.gate }} - - - name: Build - if: matrix.gate == 'test' - working-directory: ShadowsocksX-NG2 - run: task --exit-code build - - - name: Upload failed test evidence + - name: Upload failed validation evidence if: failure() uses: actions/upload-artifact@ea165f8d65b6e75b540449e92b4886f43607fa02 # v4 with: - name: validation-${{ strategy.job-index }} + name: validation-${{ github.job }} + path: ShadowsocksX-NG2/.build/validation/ + include-hidden-files: true + retention-days: 7 + if-no-files-found: warn + + build-test: + name: Build and test (Xcode 27 arm64) + runs-on: xcode-27 + timeout-minutes: 60 + steps: + - name: Check out source + uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1 + with: + persist-credentials: false + + - name: Set up dependencies + uses: ./.github/actions/setup-ng2 + + - name: Build + run: task --exit-code validate -- build + + - name: Test + run: task --exit-code validate -- test + + - name: Upload failed validation evidence + if: failure() + uses: actions/upload-artifact@ea165f8d65b6e75b540449e92b4886f43607fa02 # v4 + with: + name: validation-${{ github.job }} + path: ShadowsocksX-NG2/.build/validation/ + include-hidden-files: true + retention-days: 7 + if-no-files-found: warn + + smoke: + name: Smoke tests (Xcode 27 arm64) + runs-on: xcode-27 + timeout-minutes: 60 + steps: + - name: Check out source + uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1 + with: + persist-credentials: false + + - name: Set up dependencies + uses: ./.github/actions/setup-ng2 + + - name: Smoke tests + run: task --exit-code validate -- test:smoke + + - name: Upload failed validation evidence + if: failure() + uses: actions/upload-artifact@ea165f8d65b6e75b540449e92b4886f43607fa02 # v4 + with: + name: validation-${{ github.job }} path: ShadowsocksX-NG2/.build/validation/ include-hidden-files: true retention-days: 7 diff --git a/docs/development.md b/docs/development.md index c7b8b6e2..8985bb38 100644 --- a/docs/development.md +++ b/docs/development.md @@ -16,13 +16,13 @@ task --exit-code --taskfile ShadowsocksX-NG2/Taskfile.dist.yml validate -- forma From the project directory, use `task --exit-code validate`. From any directory, use `task --exit-code --taskfile /path/to/ShadowsocksX-NG/ShadowsocksX-NG2/Taskfile.dist.yml validate`. The entry point locates the project directory relative to the Taskfile and invokes individual tasks from the distribution Taskfile. -By default, stages run in this order: `lint → test → build`. Real-process smoke tests remain available as the explicit `test:smoke` stage. Formatting is not part of the default validation loop; pre-commit controls local formatting, and CI invokes `task format:check` separately on the Xcode 27 arm64 runner to match the Swift 6.4 formatter baseline. You can select a subset in a specified order; each stage can appear at most once. Execution stops on the first failure, marks later stages `not_run`, and exits nonzero. `--exit-code` makes Task pass through the stage's exit code. Without it, Task still exits nonzero but may use its own error code. The entry point does not retry automatically, change test parallelism, or run formatters that modify source files. +By default, stages run in this order: `lint → test → build`. Real-process smoke tests remain available as the explicit `test:smoke` stage. Formatting is not part of the default validation loop; pre-commit controls local formatting, and CI invokes `task --exit-code validate -- format:check` in a separate step on the Xcode 27 arm64 runner to match the Swift 6.4 formatter baseline. You can select a subset in a specified order; each stage can appear at most once. Execution stops on the first failure, marks later stages `not_run`, and exits nonzero. `--exit-code` makes Task pass through the stage's exit code. Without it, Task still exits nonzero but may use its own error code. The entry point does not retry automatically, change test parallelism, or run formatters that modify source files. ### Validation artifacts and evidence Each local `validate` run creates a separate `.build/validation/-/` directory and prints its absolute path at the start and end. `summary.txt` records each stage's status, exit code, and evidence status. For every executed stage, the corresponding subdirectory contains a combined stdout/stderr `raw.log` and a `status.txt` (`test:smoke` uses `test-smoke/`); Xcode stages also save `result.xcresult`. The console shows progress and a summary. Read the corresponding logs for complete errors. All artifacts are inside existing ignored directories. `task clean` deletes them, so copy anything you need to keep. -CI runs two independent matrix jobs: `test` and `test:smoke`, with fail-fast disabled. Both run through `task --exit-code validate -- ` and treat compiler warnings as errors. The `test` job also checks formatting, runs lint, and builds. Failed jobs upload retained validation logs, summaries, and result bundles for seven days. Read the uploaded `summary.txt` and `test-summary.json` first; test output is retained in `raw.log`. +CI runs three independent jobs on Xcode 27 arm64: `style` checks formatting then lint, `build-test` builds the app then runs hostless tests and offline checks, and `smoke` runs real-process tests. Each check is a separate step through `task --exit-code validate -- `, with its own retained run directory. A failed step skips later steps in the same job without stopping the other jobs. The build and test steps share DerivedData, and compiler warnings are errors. A local composite action prepares dependencies; `style` installs only Task and SwiftLint and does not fetch external binaries. Failed jobs upload retained validation logs, summaries, and result bundles for seven days under `validation-`. Read the uploaded `summary.txt` and `test-summary.json` first; complete gate output is retained in `raw.log`. For test stages, the workflow uses the local `xcrun xcresulttool get test-results summary` and system `plutil` to read test counts on a best-effort basis; it adds no scripts or tool dependencies. `test-summary.json` stores the raw summary, `test-summary.stderr.log` stores xcresulttool errors, and `count-reader.log` stores count-reading errors. The summary shows passed, failed, skipped, expected-failure, and total counts using Xcode's summary semantics; parameterized tests may have a different actual execution count. Stage and overall exit codes come from the original command, and a failed command always remains a failure. A missing result bundle or unreadable summary is marked `evidence incomplete`, with counts shown as unknown. This does not change the command result, and missing counts are never reported as zero. Build stages do not read test counts; a stage that did not run is not the same as a skipped test. diff --git a/docs/development.zh.md b/docs/development.zh.md index 109f920b..b75e621c 100644 --- a/docs/development.zh.md +++ b/docs/development.zh.md @@ -16,11 +16,13 @@ task --exit-code --taskfile ShadowsocksX-NG2/Taskfile.dist.yml validate -- forma 在工程目录内可用 `task --exit-code validate`。从任意目录可用 `task --exit-code --taskfile /path/to/ShadowsocksX-NG/ShadowsocksX-NG2/Taskfile.dist.yml validate`。入口按 Taskfile 所在位置定位工程目录,内部调用发行 Taskfile 中的单项任务。 -默认按 `lint → test → build` 执行;真实进程冒烟测试仍可显式选择 `test:smoke`。格式检查不属于默认验证循环:本地由 pre-commit 控制格式;CI 在 Xcode 27 arm64 runner 上单独运行 `task format:check`,与 Swift 6.4 格式工具基线一致。也可按指定顺序选择子集,每关最多一次;任一关失败立即停止,后续关标记 `not_run`,进程返回非零。`--exit-code` 让 Task 透传关卡退出码;省略时 Task 仍返回非零,但可能使用自己的错误码。入口不自动重试,不修改测试并行设置,也不执行会修改源码的格式化。 +默认按 `lint → test → build` 执行;真实进程冒烟测试仍可显式选择 `test:smoke`。格式检查不属于默认验证循环:本地由 pre-commit 控制格式;CI 在 Xcode 27 arm64 runner 上以独立 step 运行 `task --exit-code validate -- format:check`,与 Swift 6.4 格式工具基线一致。也可按指定顺序选择子集,每关最多一次;任一关失败立即停止,后续关标记 `not_run`,进程返回非零。`--exit-code` 让 Task 透传关卡退出码;省略时 Task 仍返回非零,但可能使用自己的错误码。入口不自动重试,不修改测试并行设置,也不执行会修改源码的格式化。 ### 验证产物与证据 -每次运行创建独立的 `.build/validation/-<随机后缀>/`,开始与结束均输出结果绝对路径。`summary.txt` 保存各关状态、退出码与证据状态;每个已执行关卡在同名子目录下保留合并 stdout/stderr 的 `raw.log` 和 `status.txt`(`test:smoke` 对应 `test-smoke/`),Xcode 关卡显式保存 `result.xcresult`。CI artifact 上传摘要、状态、日志和测试计数诊断文件,不上传 `.xcresult` 结果包,以减少下载体积;完整结果包在 job 运行期间仍保留于 runner 工作区。本地验证仍在验证目录保留全部证据。控制台只显示进度和摘要,需要完整错误时直接读取对应日志。所有产物均在现有忽略目录内;`task clean` 会删除它们,需要长期留存时先复制出去。 +每次运行创建独立的 `.build/validation/-<随机后缀>/`,开始与结束均输出结果绝对路径。`summary.txt` 保存各关状态、退出码与证据状态;每个已执行关卡在同名子目录下保留合并 stdout/stderr 的 `raw.log` 和 `status.txt`(`test:smoke` 对应 `test-smoke/`),Xcode 关卡显式保存 `result.xcresult`。本地验证保留全部证据;CI 上传策略见下文。控制台只显示进度和摘要,需要完整错误时直接读取对应日志。所有产物均在现有忽略目录内;`task clean` 会删除它们,需要长期留存时先复制出去。 + +CI 在 Xcode 27 arm64 上运行三个独立 job:`style` 依次检查格式和 lint;`build-test` 先构建应用,再执行 hostless 测试和离线检查;`smoke` 执行真实进程测试。每项检查都是独立 step,通过 `task --exit-code validate -- ` 执行,各自保留独立的结果目录。任一步失败会跳过同一 job 的后续步骤,不影响其他 job。构建和测试共用 DerivedData,编译警告视为错误。公共依赖准备由本地 composite action 完成;`style` 只安装 Task 和 SwiftLint,不下载外部二进制。失败 job 将日志、摘要和结果包上传为 `validation-`,保留七天。优先读取 `summary.txt` 和 `test-summary.json`,完整关卡输出保存在 `raw.log`。 测试关通过本机 `xcrun xcresulttool get test-results summary` 和系统 `plutil` 尽力读取计数,无需新增脚本或工具依赖。`test-summary.json` 保存原始摘要,`test-summary.stderr.log` 保存 xcresulttool 错误,`count-reader.log` 保存计数读取错误。汇总展示通过、失败、跳过、预期失败及总数(Xcode 汇总口径,参数化测试的实际执行次数可能不同)。关卡与总体退出码由原命令决定,命令失败始终保留失败。结果包缺失或摘要不可读时显著标注 `evidence incomplete`(证据不完整)、计数未知,不改变命令结果,也不把缺失计数写成零。构建关不读取测试计数;未执行的关卡不等同于测试跳过。