From c1ac50e98181dfc2f3ce2d3f8f47444f14cda37f Mon Sep 17 00:00:00 2001
From: Seungpyo1007 <rush94434@gmail.com>
Date: Fri, 31 Jul 2026 18:22:50 +0900
Subject: [PATCH] chore: adopt git-flow with a develop branch
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Every change has been landing straight on main, which is also the branch that
publishes the site and tells TechEngine to pick up new data — so any merge was
effectively a release. Adds develop as the integration branch and keeps main for
released state.

- validate-data now also runs on pushes to develop, so integration is checked
  the same way main is
- bump-engine lands the submodule bump on develop instead of pushing to main.
  It switches branch *before* updating the submodule, so the change is staged on
  the branch that will carry it rather than being committed and then orphaned
- README documents the model and points contributors at develop

deploy-pages and notify-engine deliberately stay on main: publishing and the
engine handshake should happen on release, not on every integration merge.
---
 .github/workflows/bump-engine.yml   | 11 +++++++++--
 .github/workflows/validate-data.yml |  2 +-
 README.md                           | 22 ++++++++++++++++++----
 3 files changed, 28 insertions(+), 7 deletions(-)

diff --git a/.github/workflows/bump-engine.yml b/.github/workflows/bump-engine.yml
index 394a4625eb44..f6464ad448da 100644
--- a/.github/workflows/bump-engine.yml
+++ b/.github/workflows/bump-engine.yml
@@ -32,6 +32,13 @@ jobs:
       - name: Update TechEngine submodule to latest main
         id: bump
         run: |
+          # git-flow: the bump is integration work, so it lands on develop.
+          # main only moves through a release PR. Switch branch BEFORE touching
+          # the submodule so the change is staged on the branch it will be
+          # committed to.
+          git fetch origin develop
+          git checkout -B develop origin/develop
+          git submodule update --init --recursive TechEngine
           git submodule update --remote --recursive TechEngine
           if git diff --quiet -- TechEngine; then
             echo "changed=false" >> "$GITHUB_OUTPUT"
@@ -51,8 +58,8 @@ jobs:
           git config user.email "289859915+TechEngineBot@users.noreply.github.com"
           git add TechEngine
           git commit -m "chore: bump TechEngine submodule to ${NEW_SHA}"
-          git pull --rebase origin main
-          git push origin HEAD:main
+          git pull --rebase origin develop
+          git push origin HEAD:develop
           echo "techapi_sha=$(git rev-parse HEAD)" >> "$GITHUB_OUTPUT"
 
       - name: Dispatch reciprocal TechAPI bump to TechEngine
diff --git a/.github/workflows/validate-data.yml b/.github/workflows/validate-data.yml
index eb276b3b8630..382e40f2ce13 100644
--- a/.github/workflows/validate-data.yml
+++ b/.github/workflows/validate-data.yml
@@ -8,7 +8,7 @@ on:
       - "data/**"
       - "app/validate.py"
   push:
-    branches: [main]
+    branches: [main, develop]
     paths:
       - "data/**"
       - "app/validate.py"
diff --git a/README.md b/README.md
index 8c9535fe59be..912c8354c25d 100644
--- a/README.md
+++ b/README.md
@@ -46,12 +46,26 @@ python -m app.validate
 
 The validator uses only the Python standard library; no install step required.
 
+## Branching
+
+This repo follows git-flow:
+
+| Branch | Role |
+| --- | --- |
+| `main` | Released state. Publishing the site and notifying TechEngine both fire on a push here, so it only moves through a release PR. |
+| `develop` | Integration. Every data, feature and fix branch targets this. |
+| `feat/*`, `data/*`, `fix/*`, `chore/*` | Short-lived work branches, cut from `develop`. |
+
+A release is a PR from `develop` to `main`; merging it deploys the site and tells
+TechEngine to pick up the new data. Automation follows the same rule — the
+submodule bump and the verified-promotion bot both land on `develop`.
+
 ## Contributing
 
-Open a PR with the new/updated JSON file. The PR template walks through what to
-include. The validator must pass. All records (`brand`, `soc`, `smartphone`,
-`gpu`, and `cpu`) must include `source_urls` with at least one canonical
-reference (vendor product page, Wikipedia infobox, datasheet).
+Open a PR **against `develop`** with the new/updated JSON file. The PR template
+walks through what to include. The validator must pass. All records (`brand`,
+`soc`, `smartphone`, `gpu`, and `cpu`) must include `source_urls` with at least
+one canonical reference (vendor product page, Wikipedia infobox, datasheet).
 
 ## License