From a4a022acc60cd064d8e7d25211a30e4e946b8a64 Mon Sep 17 00:00:00 2001 From: "Richard.Lu" Date: Fri, 4 Sep 2026 19:53:28 +0800 Subject: [PATCH] =?UTF-8?q?chore:=20=E5=BB=BA=E7=AB=8Bdevelop=E6=B5=8B?= =?UTF-8?q?=E8=AF=95=E9=9B=86=E6=88=90=E5=9F=BA=E7=BA=BF=20/=20establish?= =?UTF-8?q?=20develop=20test=20integration=20baseline?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 将CI、主分支来源守卫、保护脚本和贡献文档统一到develop -> main工作流。\nAlign CI, main-source guard, protection tooling, and contribution docs with the develop -> main workflow. --- .github/scripts/apply-branch-protection.sh | 16 ++++++++-------- .github/workflows/branch-guard.yml | 18 +++++++++--------- .github/workflows/ci.yml | 4 ++-- .pre-commit-config.yaml | 5 ++--- CONTRIBUTING.md | 22 +++++++++++----------- CONTRIBUTING_EN.md | 18 +++++++++--------- 6 files changed, 41 insertions(+), 42 deletions(-) diff --git a/.github/scripts/apply-branch-protection.sh b/.github/scripts/apply-branch-protection.sh index 8a4c23e..a543310 100755 --- a/.github/scripts/apply-branch-protection.sh +++ b/.github/scripts/apply-branch-protection.sh @@ -1,6 +1,6 @@ #!/usr/bin/env bash -# 在 GitHub 上启用 main / staging 分支保护（需仓库 admin + gh 已登录） -# Enable GitHub branch protection for main and staging (requires admin + gh auth) +# 在 GitHub 上启用 main / develop 分支保护（需仓库 admin + gh 已登录） +# Enable GitHub branch protection for main and develop (requires admin + gh auth) # # 用法 / Usage: # gh auth login @@ -20,7 +20,7 @@ if ! gh auth status >/dev/null 2>&1; then exit 1 fi -echo "🔒 配置 main：禁止直接 push，仅允许 staging PR 晋级" +echo "🔒 配置 main：禁止直接 push，仅允许 develop PR 晋级" echo " Configure main: block direct pushes; merge via PR only" gh api "repos/${REPO}/branches/main/protection" -X PUT \ @@ -35,19 +35,19 @@ gh api "repos/${REPO}/branches/main/protection" -X PUT \ -F 'required_status_checks[contexts][]=test (3.11)' \ -F 'required_status_checks[contexts][]=test (3.12)' \ -F 'required_status_checks[contexts][]=lint' \ - -F 'required_status_checks[contexts][]=require-staging-source' \ + -F 'required_status_checks[contexts][]=require-develop-source' \ 2>/dev/null || { echo "⚠️ main 保护需 classic protection 或 Rulesets 权限；若失败请在 GitHub UI 手动设置：" echo " Settings → Branches → Add rule for main" echo " - Require a pull request before merging" - echo " - Require status check: require-staging-source" + echo " - Require status check: require-develop-source" echo " - Do not allow bypassing" echo " - Restrict pushes that create files (optional)" } echo "" -echo "🔒 配置 staging：禁止直接 push，仅允许 feature/fix 分支通过 PR 合入" -gh api "repos/${REPO}/branches/staging/protection" -X PUT \ +echo "🔒 配置 develop：禁止直接 push，仅允许 feature/fix 分支通过 PR 合入" +gh api "repos/${REPO}/branches/develop/protection" -X PUT \ -f required_status_checks[strict]=false \ -f enforce_admins=false \ -f required_pull_request_reviews[required_approving_review_count]=0 \ @@ -59,7 +59,7 @@ gh api "repos/${REPO}/branches/staging/protection" -X PUT \ -F 'required_status_checks[contexts][]=test (3.12)' \ -F 'required_status_checks[contexts][]=lint' \ 2>/dev/null || { - echo "⚠️ staging 保护可选；建议在 UI 为 staging 启用 Require PR（feature/fix → staging）" + echo "⚠️ develop 保护需在 GitHub UI 或 Rulesets 中启用 Require PR（feature/fix → develop）" } echo "" diff --git a/.github/workflows/branch-guard.yml b/.github/workflows/branch-guard.yml index d4de9b2..1cb6865 100644 --- a/.github/workflows/branch-guard.yml +++ b/.github/workflows/branch-guard.yml @@ -1,5 +1,5 @@ -# 分支策略守卫：main 只能由 staging PR 晋级 -# Branch guard: main can only be promoted from staging PRs +# 分支策略守卫：main 只能由 develop PR 晋级 +# Branch guard: main can only be promoted from develop PRs # # 说明 / Note: push 守卫是兜底；真正阻断直接更新依赖 GitHub Rulesets。 # Push guard is a fallback; GitHub Rulesets are what block direct updates. @@ -13,7 +13,7 @@ on: branches: [main] jobs: - require-staging-source: + require-develop-source: if: github.event_name == 'pull_request' runs-on: ubuntu-latest steps: @@ -22,12 +22,12 @@ jobs: HEAD_REF: ${{ github.head_ref }} run: | set -euo pipefail - if [[ "${HEAD_REF}" == "staging" ]]; then - echo "Allowed: staging -> main" + if [[ "${HEAD_REF}" == "develop" ]]; then + echo "Allowed: develop -> main" exit 0 fi - echo "::error::main 只能从 staging 分支通过 PR 晋级，当前来源：${HEAD_REF}" - echo "::error::PRs to main must come from staging. Current source: ${HEAD_REF}" + echo "::error::main 只能从 develop 分支通过 PR 晋级，当前来源：${HEAD_REF}" + echo "::error::PRs to main must come from develop. Current source: ${HEAD_REF}" exit 1 block-direct-push-to-main: @@ -48,6 +48,6 @@ jobs: echo "Allowed merge to main." exit 0 fi - echo "::error::禁止直接向 main 推送。请先合入 staging，再通过 PR 合入 main。" - echo "::error::Direct push to main is not allowed. Merge to staging first, then open a PR to main." + echo "::error::禁止直接向 main 推送。请先合入 develop，再通过 PR 合入 main。" + echo "::error::Direct push to main is not allowed. Merge to develop first, then open a PR to main." exit 1 diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index 197e16d..11ac3ad 100644 --- a/.github/workflows/ci.yml +++ b/.github/workflows/ci.yml @@ -2,9 +2,9 @@ name: CI on: push: - branches: [ main, staging ] + branches: [ main, develop ] pull_request: - branches: [ main, staging ] + branches: [ main, develop ] jobs: test: diff --git a/.pre-commit-config.yaml b/.pre-commit-config.yaml index 92dd483..d4bcebe 100644 --- a/.pre-commit-config.yaml +++ b/.pre-commit-config.yaml @@ -11,9 +11,9 @@ repos: - id: check-toml - id: check-merge-conflict - id: debug-statements - # 禁止在 main 上直接 commit / Block direct commits on main + # 禁止在长期受保护分支上直接提交 / Block direct commits on protected branches - id: no-commit-to-branch - args: [--branch, main] + args: [--branch, main, --branch, develop] - repo: https://github.com/psf/black rev: 24.1.1 @@ -33,4 +33,3 @@ repos: - id: mypy additional_dependencies: [types-all] args: [--ignore-missing-imports] - diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 7e37ef4..befec3b 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -33,11 +33,11 @@ cd OGScope ``` -2. **基于 staging 创建功能分支 / Branch from staging** +2. **基于 develop 创建功能分支 / Branch from develop** ```bash git fetch origin - git checkout staging - git pull origin staging + git checkout develop + git pull origin develop git checkout -b feature/your-feature-name ``` @@ -125,16 +125,16 @@ | 分支 | 用途 | |------|------| -| `main` | 稳定发布线；仅通过 PR 从 `staging` 晋级 | -| `staging` | **长期测试集成分支**；日常开发、板端联调与社区测试基准 | -| `feature/*` | 功能/重构；从 `staging` 拉出，PR 合回后删除 | -| `fix/*` | 小修复；合入 `staging` 验证，紧急时可 hotfix 合 `main` | +| `main` | 稳定发布线；仅通过 PR 从 `develop` 晋级 | +| `develop` | **长期测试集成分支**；日常开发、板端联调与社区测试基准 | +| `feature/*` | 功能/重构；从 `develop` 拉出，PR 合回后删除 | +| `fix/*` | 小修复；合入 `develop` 验证，紧急修复也必须先回合 `develop` | -流程：`feature/*` / `fix/*` → PR → `staging` → 测试通过后 PR → `main`。 +流程：`feature/*` / `fix/*` → PR → `develop` → 测试通过后 PR → `main`。 -**禁止直接向 `main` 或 `staging` 提交或推送**（本地 pre-commit 会拦截；remote 需配置 GitHub Rulesets 或 Branch protection，见 [.github/scripts/apply-branch-protection.sh](../.github/scripts/apply-branch-protection.sh)）。 +**禁止直接向 `main` 或 `develop` 提交或推送**（本地 pre-commit 会拦截；远端通过 GitHub Rulesets 强制执行，见 [.github/scripts/apply-branch-protection.sh](.github/scripts/apply-branch-protection.sh)）。 -**已废弃**：不再使用 `develop`、`dev`、`dev-latest` 集成分支。 +**已废弃**：不再使用 `staging`、`dev`、`dev-latest` 集成分支。 ## 开发流程 @@ -142,7 +142,7 @@ 2. **开发**: 在本地开发和测试 3. **提交 PR**: 创建 Pull Request 4. **代码审查**: 等待维护者审查 -5. **合并**: 审查通过后合并到 `staging`，测试通过后再通过 PR 晋级 `main` +5. **合并**: 审查通过后合并到 `develop`，测试通过后再通过 PR 晋级 `main` ## 代码审查标准 diff --git a/CONTRIBUTING_EN.md b/CONTRIBUTING_EN.md index 08f1090..77b54be 100644 --- a/CONTRIBUTING_EN.md +++ b/CONTRIBUTING_EN.md @@ -24,7 +24,7 @@ Thank you for your interest in OGScope. We welcome contributions of all kinds. ### Code contributions 1. **Fork** the repository and clone your fork. -2. **Branch from `staging`**: `git checkout staging && git pull && git checkout -b feature/your-feature-name` +2. **Branch from `develop`**: `git checkout develop && git pull && git checkout -b feature/your-feature-name` 3. **Dev dependencies**: ```bash poetry install @@ -80,16 +80,16 @@ Thank you for your interest in OGScope. We welcome contributions of all kinds. | Branch | Purpose | |--------|---------| -| `main` | Stable release; promote from `staging` via PR only | -| `staging` | **Long-lived test integration branch**; default for daily work, board sync, and community validation | -| `feature/*` | Features/refactors; branch from `staging`, delete after merge | -| `fix/*` | Small fixes; validate through `staging`; hotfix to `main` when urgent | +| `main` | Stable release; promote from `develop` via PR only | +| `develop` | **Long-lived test integration branch**; default for daily work, board sync, and community validation | +| `feature/*` | Features/refactors; branch from `develop`, delete after merge | +| `fix/*` | Small fixes; validate through `develop`; urgent fixes must still merge back through `develop` | -Flow: `feature/*` / `fix/*` → PR → `staging` → validated PR → `main`. +Flow: `feature/*` / `fix/*` → PR → `develop` → validated PR → `main`. -**Do not commit or push directly to `main` or `staging`.** Local pre-commit blocks this; configure GitHub Rulesets or branch protection via [.github/scripts/apply-branch-protection.sh](../.github/scripts/apply-branch-protection.sh). +**Do not commit or push directly to `main` or `develop`.** Local pre-commit blocks this; GitHub Rulesets enforce the remote policy. See [.github/scripts/apply-branch-protection.sh](.github/scripts/apply-branch-protection.sh). -**Deprecated**: `develop`, `dev`, and `dev-latest` integration branches. +**Deprecated**: `staging`, `dev`, and `dev-latest` integration branches. ## Workflow @@ -97,7 +97,7 @@ Flow: `feature/*` / `fix/*` → PR → `staging` → validated PR → `main`. 2. Develop and test locally 3. Open a PR 4. Review -5. Merge into `staging`, then promote to `main` by PR after validation +5. Merge into `develop`, then promote to `main` by PR after validation ## Review expectations