Initial commit

2026-05-25 11:01:58 +00:00
commit b36de765c0
8 changed files with 471 additions and 0 deletions
@@ -0,0 +1,100 @@
+# coa-template
+
+Template repo for new `Exiles/coa-*` addon forks. Click **Use This
+Template** on the Gitea page to start a fresh repo with the canonical
+release pipeline, layout convention, and CoA porting checklist
+pre-wired.
+
+## What you get
+
+```
+.
+├── .gitea/workflows/release.yml   # tag-triggered release pipeline
+├── tools/
+│   ├── build_zip.sh               # git-archive per addon folder
+│   └── init_from_upstream.sh      # one-shot upstream import helper
+├── .gitattributes                 # * -text (preserve upstream EOLs)
+├── .gitignore                     # standard 7-line + dist/
+├── LICENSE                        # 0BSD
+├── PORTING.md                     # CoA-compat bug-pattern checklist
+└── README.md                      # this file
+```
+
+## Quick start (backporting an existing addon)
+
+```sh
+# 1. Use this template to create Exiles/coa-myaddon, then:
+git clone gitea@git.sub-net.at:Exiles/coa-myaddon.git
+cd coa-myaddon
+
+# 2. Pull the upstream source into MyAddon/ at the repo root.
+tools/init_from_upstream.sh \
+  https://github.com/Ascension-Addons/MyAddon \
+  MyAddon
+
+# 3. Make it run on CoA. Read PORTING.md — every recurring failure mode
+#    we've seen across the existing 25 Exiles forks is documented there
+#    with the matching fix.
+
+# 4. Verify the build works.
+bash tools/build_zip.sh
+unzip -l dist/MyAddon.zip | head -5     # first entry: MyAddon/
+
+# 5. Push your fork.
+git push origin master
+
+# 6. Tag the first release. Read MyAddon/MyAddon.toc for the upstream
+#    version, then:
+git tag -a 1.2.3-coa.1 -m "first Exiles release"
+git push origin 1.2.3-coa.1
+
+# The runner picks it up within seconds and publishes
+# https://git.sub-net.at/Exiles/coa-myaddon/releases/tag/1.2.3-coa.1
+```
+
+## Layout convention
+
+Every addon source folder sits at the repo root with the same name as
+its `.toc`:
+
+```
+coa-myaddon/
+├── MyAddon/
+│   ├── MyAddon.toc
+│   └── ...
+└── (dev tooling at root)
+```
+
+Multi-addon repos (DBM, Altoholic, Atlasloot, …) place each addon as a
+sibling folder at the repo root. `tools/build_zip.sh` discovers them all
+and emits one zip per addon plus a combined `coa-myaddon-all.zip`.
+
+## Release pipeline
+
+The workflow in `.gitea/workflows/release.yml` triggers on tags matching
+`*-coa.*` or `v*`. It checks out, runs `tools/build_zip.sh`, and uploads
+each `dist/*.zip` as a Gitea release attachment via plain `curl` — no
+external action dependency, no org-level secret. Per-asset upload
+failures are tolerated (the job still publishes whatever uploaded);
+oversized assets (>200 MiB) get a `::warning` and skip.
+
+Runner: `gitea-runner01.corp.sub-net.at` (host executor, label
+`linux-amd64`). Configured by the `gitea_runner` Ansible role.
+
+Full docs: [coa.exil.es/coa/dev/releases](https://coa.exil.es/coa/dev/releases).
+
+## Maintenance
+
+This template is updated by hand when the canonical files in
+`Exiles/coa-decursive` (the pilot) change. To re-sync the canonical
+release pipeline from the pilot:
+
+```sh
+cp /path/to/coa-decursive/tools/build_zip.sh tools/build_zip.sh
+cp /path/to/coa-decursive/.gitea/workflows/release.yml .gitea/workflows/release.yml
+```
+
+The PORTING.md checklist is the lean snapshot of
+[coa.exil.es/coa/dev/addons](https://coa.exil.es/coa/dev/addons) — when
+you discover a new CoA failure mode, add it to the Tome page first, then
+re-snapshot here.