# 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.