Add "Patch-Release-Workflow"

2026-07-01 15:41:27 +08:00
parent b2958b951e
commit 47a943311d
1 changed files with 64 additions and 0 deletions
@@ -0,0 +1,64 @@
+# Patch Release Workflow
+
+How to ship new features and assets to live players.
+
+## 1. Write the Changelog
+
+- Document your changes in `CHANGELOG_DRAFT.md` in **player-friendly language** under the `## [NEXT]` section.
+
+## 2. Bump the Version
+
+- Run the version script from a terminal:
+  ```bash
+  python generate_version_json.py --bump patch
+  ```
+  Use `--bump minor` or `--bump major` for larger updates.
+
+## 3. Commit and Push
+
+```bash
+git add .
+git commit -m "Release version X.Y.Z"
+git push origin main
+```
+
+The **GitHub Actions workflow** (`.github/workflows/deploy_patch.yml`) detects the push, builds the patch manifest (`version.json`), and deploys it to the public `gh-pages` branch.
+
+## 4. Players Receive the Patch
+
+Live game clients detect the new version on boot, download the updated files, and apply the patch seamlessly.
+
+## How the Patch System Works
+
+When a player downloads an in-game patch, Godot fetches a `patch.pck` file into the system's `user://` directory.
+
+- **Virtual File System:** Godot mounts the `.pck` over `res://` purely in memory. It does **not** physically overwrite your local source files (e.g. `assets/data/version.json`).
+- **Editor Bypass:** When testing locally in the Godot Editor, `BootScreen` skips the remote download and reads your *local* `assets/data/version.json` directly.
+- **Previewing Changelogs:**
+  - Add your notes under `## [NEXT]` in `CHANGELOG_DRAFT.md`.
+  - Run `py tools/generate_version_json.py`.
+  - Run the `BootScreen` scene — it instantly renders the updated local UI.
+- **Syncing:** After CI builds a release online, run `git pull origin main` to sync your local project with the CI-generated files.
+
+## Architecture
+
+```mermaid
+flowchart TD
+    subgraph Local Dev Environment
+        A[CHANGELOG_DRAFT.md] -->|py tools/generate_version_json.py| B[version.json]
+        B -.->|Test in Editor| C{BootScreen}
+        C -- Editor Bypass --> D[Reads Local version.json]
+    end
+
+    subgraph CI/CD Pipeline
+        B -->|git push| E[GitHub Actions]
+        E -->|Builds| F[patch.pck]
+        F -->|Deploys| G((Public Repo))
+    end
+
+    subgraph Player Client
+        G -.->|HTTP Download on Boot| H[user://patch.pck]
+        H -->|load_resource_pack| I[Godot Virtual File System]
+        I -.->|Overrides res://| J[Game Starts Updated]
+    end
+```