docs: update patch workflow for Gitea Pages
+133
-37
@@ -1,64 +1,160 @@
|
|||||||
# Patch Release Workflow
|
# Patch Release Workflow
|
||||||
|
|
||||||
How to ship new features and assets to live players.
|
How to ship resource/script/asset updates to live desktop players without replacing the full game binary.
|
||||||
|
|
||||||
## 1. Write the Changelog
|
## Platform support
|
||||||
|
|
||||||
- Document your changes in `CHANGELOG_DRAFT.md` in **player-friendly language** under the `## [NEXT]` section.
|
One shared `patch.pck` is used by all desktop builds:
|
||||||
|
|
||||||
## 2. Bump the Version
|
- Windows ✅
|
||||||
|
- Linux ✅
|
||||||
|
- macOS ✅
|
||||||
|
|
||||||
- Run the version script from a terminal:
|
This works because Godot mounts `.pck` files into the virtual `res://` filesystem. Platform does not matter for normal Godot resources, scenes, scripts, textures, audio, and data files.
|
||||||
```bash
|
|
||||||
python generate_version_json.py --bump patch
|
|
||||||
```
|
|
||||||
Use `--bump minor` or `--bump major` for larger updates.
|
|
||||||
|
|
||||||
## 3. Commit and Push
|
Use a full release (`ci.yml`) instead when the change touches platform-native pieces:
|
||||||
|
|
||||||
```bash
|
- Windows `.exe`
|
||||||
git add .
|
- Linux executable wrapper
|
||||||
git commit -m "Release version X.Y.Z"
|
- macOS `.app`, signing, entitlements
|
||||||
git push origin main
|
- native plugins: `.dll`, `.so`, `.dylib`
|
||||||
|
- export templates or engine/runtime version
|
||||||
|
- anything that must exist before Godot can start
|
||||||
|
|
||||||
|
## Public patch URLs
|
||||||
|
|
||||||
|
Players download patch metadata and content from Gitea Pages:
|
||||||
|
|
||||||
|
```text
|
||||||
|
https://raw.klud.top/danchie/tekton/version.json
|
||||||
|
https://raw.klud.top/danchie/tekton/patch.pck
|
||||||
```
|
```
|
||||||
|
|
||||||
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.
|
`raw.klud.top` is Caddy reverse proxy → `gitea-pages` container → `patches` branch of this repo.
|
||||||
|
|
||||||
## 4. Players Receive the Patch
|
No client auth required.
|
||||||
|
|
||||||
Live game clients detect the new version on boot, download the updated files, and apply the patch seamlessly.
|
## 1. Write changelog
|
||||||
|
|
||||||
## How the Patch System Works
|
Edit `CHANGELOG_DRAFT.md` and add player-facing notes under:
|
||||||
|
|
||||||
When a player downloads an in-game patch, Godot fetches a `patch.pck` file into the system's `user://` directory.
|
```md
|
||||||
|
## [NEXT]
|
||||||
|
```
|
||||||
|
|
||||||
- **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`).
|
Example:
|
||||||
- **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:**
|
```md
|
||||||
- Add your notes under `## [NEXT]` in `CHANGELOG_DRAFT.md`.
|
## [NEXT]
|
||||||
- Run `py tools/generate_version_json.py`.
|
- Fixed Ghost powerup not bypassing sticky tiles.
|
||||||
- Run the `BootScreen` scene — it instantly renders the updated local UI.
|
- Added new Gauntlet reward UI polish.
|
||||||
- **Syncing:** After CI builds a release online, run `git pull origin main` to sync your local project with the CI-generated files.
|
```
|
||||||
|
|
||||||
|
## 2. Preview locally
|
||||||
|
|
||||||
|
Generate local `assets/data/version.json`:
|
||||||
|
|
||||||
|
```bash
|
||||||
|
python3 tools/generate_version_json.py --local
|
||||||
|
```
|
||||||
|
|
||||||
|
Run `BootScreen` in Godot. Editor mode skips remote download and reads local `assets/data/version.json`.
|
||||||
|
|
||||||
|
## 3. Commit changes to `experimental`
|
||||||
|
|
||||||
|
```bash
|
||||||
|
git add CHANGELOG_DRAFT.md assets/data/version.json project.godot export_presets.cfg
|
||||||
|
git commit -m "chore: prepare patch notes"
|
||||||
|
git push origin experimental
|
||||||
|
```
|
||||||
|
|
||||||
|
## 4. Run Gitea Actions patch deploy
|
||||||
|
|
||||||
|
Open:
|
||||||
|
|
||||||
|
```text
|
||||||
|
https://git.klud.top/danchie/tekton/actions
|
||||||
|
```
|
||||||
|
|
||||||
|
Run workflow:
|
||||||
|
|
||||||
|
```text
|
||||||
|
Deploy Patch
|
||||||
|
```
|
||||||
|
|
||||||
|
The workflow `.gitea/workflows/deploy_patch.yml` does this:
|
||||||
|
|
||||||
|
1. Clones repo using `god` token.
|
||||||
|
2. Installs Godot 4.7 stable.
|
||||||
|
3. Runs `tools/generate_version_json.py --skip-changelog`.
|
||||||
|
4. Builds one shared `build/patch.pck` with `godot --headless --export-pack`.
|
||||||
|
5. Pushes `version.json` + `patch.pck` to the `patches` branch.
|
||||||
|
6. `gitea-pages` serves them at `https://raw.klud.top/danchie/tekton/...`.
|
||||||
|
|
||||||
|
## 5. Verify deploy
|
||||||
|
|
||||||
|
Check manifest:
|
||||||
|
|
||||||
|
```bash
|
||||||
|
curl https://raw.klud.top/danchie/tekton/version.json
|
||||||
|
```
|
||||||
|
|
||||||
|
Check patch file exists:
|
||||||
|
|
||||||
|
```bash
|
||||||
|
curl -I https://raw.klud.top/danchie/tekton/patch.pck
|
||||||
|
```
|
||||||
|
|
||||||
|
Expected: HTTP `200`.
|
||||||
|
|
||||||
|
## 6. Players receive patch
|
||||||
|
|
||||||
|
On boot, game client fetches:
|
||||||
|
|
||||||
|
```gdscript
|
||||||
|
const VERSION_MANIFEST_URL := "https://raw.klud.top/danchie/tekton/version.json"
|
||||||
|
```
|
||||||
|
|
||||||
|
If remote version is newer, client downloads `patch.pck` to `user://` and mounts it with `ProjectSettings.load_resource_pack(...)`.
|
||||||
|
|
||||||
|
## How the patch system works
|
||||||
|
|
||||||
|
- **Virtual filesystem:** Godot mounts `patch.pck` over `res://` in memory.
|
||||||
|
- **No physical overwrite:** Local source files are not changed.
|
||||||
|
- **Override priority:** Files inside mounted patch can override base game files with same paths.
|
||||||
|
- **Editor bypass:** In Godot Editor, `BootScreen` uses local `assets/data/version.json` for fast preview.
|
||||||
|
|
||||||
## Architecture
|
## Architecture
|
||||||
|
|
||||||
```mermaid
|
```mermaid
|
||||||
flowchart TD
|
flowchart TD
|
||||||
subgraph Local Dev Environment
|
subgraph Local Dev
|
||||||
A[CHANGELOG_DRAFT.md] -->|py tools/generate_version_json.py| B[version.json]
|
A[CHANGELOG_DRAFT.md] -->|tools/generate_version_json.py --local| B[assets/data/version.json]
|
||||||
B -.->|Test in Editor| C{BootScreen}
|
B -->|Editor preview| C[BootScreen]
|
||||||
C -- Editor Bypass --> D[Reads Local version.json]
|
|
||||||
end
|
end
|
||||||
|
|
||||||
subgraph CI/CD Pipeline
|
subgraph Gitea Actions
|
||||||
B -->|git push| E[GitHub Actions]
|
D[Deploy Patch workflow] --> E[Godot 4.7 export-pack]
|
||||||
E -->|Builds| F[patch.pck]
|
E --> F[patch.pck]
|
||||||
F -->|Deploys| G((Public Repo))
|
F --> G[push version.json + patch.pck]
|
||||||
|
end
|
||||||
|
|
||||||
|
subgraph Hosting
|
||||||
|
G --> H[patches branch]
|
||||||
|
H --> I[gitea-pages]
|
||||||
|
I --> J[https://raw.klud.top/danchie/tekton]
|
||||||
end
|
end
|
||||||
|
|
||||||
subgraph Player Client
|
subgraph Player Client
|
||||||
G -.->|HTTP Download on Boot| H[user://patch.pck]
|
J -->|download version.json| K[Compare versions]
|
||||||
H -->|load_resource_pack| I[Godot Virtual File System]
|
K -->|download patch.pck| L[user://patch.pck]
|
||||||
I -.->|Overrides res://| J[Game Starts Updated]
|
L -->|load_resource_pack| M[Godot res:// overlay]
|
||||||
|
M --> N[Game starts patched]
|
||||||
end
|
end
|
||||||
```
|
```
|
||||||
|
|
||||||
|
## Rule of thumb
|
||||||
|
|
||||||
|
Use patch deploy for Godot content changes.
|
||||||
|
|
||||||
|
Use full release for engine, native, executable, signing, or platform-specific changes.
|
||||||
|
|||||||
Reference in New Issue
Block a user