docs: update patch workflow for Gitea Pages
+133
-37
@@ -1,64 +1,160 @@
|
||||
# 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:
|
||||
```bash
|
||||
python generate_version_json.py --bump patch
|
||||
```
|
||||
Use `--bump minor` or `--bump major` for larger updates.
|
||||
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.
|
||||
|
||||
## 3. Commit and Push
|
||||
Use a full release (`ci.yml`) instead when the change touches platform-native pieces:
|
||||
|
||||
```bash
|
||||
git add .
|
||||
git commit -m "Release version X.Y.Z"
|
||||
git push origin main
|
||||
- Windows `.exe`
|
||||
- Linux executable wrapper
|
||||
- macOS `.app`, signing, entitlements
|
||||
- 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`).
|
||||
- **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.
|
||||
Example:
|
||||
|
||||
```md
|
||||
## [NEXT]
|
||||
- Fixed Ghost powerup not bypassing sticky tiles.
|
||||
- Added new Gauntlet reward UI polish.
|
||||
```
|
||||
|
||||
## 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
|
||||
|
||||
```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]
|
||||
subgraph Local Dev
|
||||
A[CHANGELOG_DRAFT.md] -->|tools/generate_version_json.py --local| B[assets/data/version.json]
|
||||
B -->|Editor preview| C[BootScreen]
|
||||
end
|
||||
|
||||
subgraph CI/CD Pipeline
|
||||
B -->|git push| E[GitHub Actions]
|
||||
E -->|Builds| F[patch.pck]
|
||||
F -->|Deploys| G((Public Repo))
|
||||
subgraph Gitea Actions
|
||||
D[Deploy Patch workflow] --> E[Godot 4.7 export-pack]
|
||||
E --> F[patch.pck]
|
||||
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
|
||||
|
||||
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]
|
||||
J -->|download version.json| K[Compare versions]
|
||||
K -->|download patch.pck| L[user://patch.pck]
|
||||
L -->|load_resource_pack| M[Godot res:// overlay]
|
||||
M --> N[Game starts patched]
|
||||
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