initialise the gitea workflows.

2026-08-22 19:35:26 +01:00
parent c5f1482aea
commit 60f552ba6a
3 changed files with 190 additions and 0 deletions
@@ -0,0 +1,182 @@
+# Minecraft Modpacks
+
+Packwiz-managed Minecraft modpacks used by the AGS Minecraft infrastructure.
+
+The repository is the source of truth for both client and server modpack configuration. Packs are deployed through Gitea Actions and served as static Packwiz repositories for Pterodactyl.
+
+## Packs
+
+### Forever World
+
+Long-lived NeoForge survival world with a deliberately conservative mod selection.
+
+- Minecraft: 1.21.1
+- NeoForge: 21.1.248
+- Packwiz: managed
+- Production: release-based
+
+Development:
+
+```text
+https://mc.ahmza.com/forever/dev/pack.toml
+```
+
+Stable:
+
+```text
+https://mc.ahmza.com/forever/stable/pack.toml
+```
+
+### Playground
+
+Disposable environment for testing mods, updates and configuration changes before considering them for Forever World.
+
+Development:
+
+```text
+https://mc.ahmza.com/playground/dev/pack.toml
+```
+
+## Repository Structure
+
+```text
+mc-modpacks/
+├── .gitea/
+│   └── workflows/
+├── forever/
+│   ├── pack.toml
+│   ├── index.toml
+│   ├── mods/
+│   ├── config/
+│   ├── defaultconfigs/
+│   └── README.md
+├── playground/
+│   ├── pack.toml
+│   ├── index.toml
+│   ├── mods/
+│   ├── config/
+│   ├── defaultconfigs/
+│   └── README.md
+└── deploy/
+    └── kubernetes/
+```
+
+## Development Model
+
+`main` represents the current development state.
+
+Normal changes are committed directly to `main`:
+
+```bash
+git switch main
+
+cd forever
+packwiz update <mod>
+packwiz refresh
+
+git add .
+git commit -m "Update <mod>"
+git push
+```
+
+A push to `main` publishes the pack to its `dev` endpoint.
+
+Production is **not** updated by normal commits.
+
+### Branches
+
+Branches are reserved for substantial or experimental work, for example:
+
+```text
+mc-26-migration
+create-major-upgrade
+worldgen-experiment
+test-new-content-mod
+```
+
+Small mod updates and configuration changes do not require branches.
+
+## Releases
+
+Test the development pack before creating a release.
+
+Forever World releases use annotated tags:
+
+```bash
+git tag -a forever-v1.0.1 -m "Forever World v1.0.1"
+git push origin forever-v1.0.1
+```
+
+A release publishes an immutable copy to:
+
+```text
+/forever/releases/v1.0.1/
+```
+
+and promotes the same build to:
+
+```text
+/forever/stable/
+```
+
+Production Pterodactyl servers always consume the stable endpoint rather than individual release URLs.
+
+### Versioning
+
+Approximately follow semantic versioning:
+
+| Version | Use |
+|---|---|
+| `v1.0.1` | Bug fixes, configs and routine mod updates |
+| `v1.1.0` | New functionality or compatible mods |
+| `v2.0.0` | Major Minecraft/modpack/world dependency changes |
+
+Release tags are immutable. Never move or recreate an existing release tag.
+
+## Deployment Flow
+
+```text
+                         Gitea
+                           │
+                     push to main
+                           │
+                           ▼
+                    Gitea Actions
+                           │
+                           ▼
+                /forever/dev/pack.toml
+                           │
+                           ▼
+                    Staging Server
+                           │
+                         Test
+                           │
+                  forever-v1.x.x tag
+                           │
+                           ▼
+                    Gitea Actions
+                      ┌────┴────┐
+                      ▼         ▼
+                  releases/   stable/
+                                │
+                                ▼
+                         Production Server
+```
+
+Packwiz is responsible for modpack contents and side filtering.
+
+Pterodactyl is responsible for Java, server process management and resources.
+
+Kubernetes/SWS provides static hosting for the published Packwiz repositories.
+
+## Rollback
+
+Release directories are immutable.
+
+If a release causes problems, production can be pointed temporarily at an earlier release:
+
+```text
+https://mc.ahmza.com/forever/releases/v1.0.1/pack.toml
+```
+
+Do not rewrite an existing release or tag. Fix the issue on `main` and publish a new release.