From eccff6f68734370962e621a873ab69f7cd845225 Mon Sep 17 00:00:00 2001 From: RubyJ Date: Mon, 16 Mar 2026 23:58:06 -0400 Subject: [PATCH 1/2] chore: add GitHub Actions CI/CD, luacheck, and BigWigs packager --- .github/workflows/release.yml | 28 ++++++++++++++++++++++ .gitignore | 2 ++ .luacheckrc | 25 ++++++++++++++++++++ .pkgmeta | 8 +++++++ AGENTS.md | 27 +++++++++++++++++++++ README.md | 44 ++++++++++++++++++++++++++++------- 6 files changed, 125 insertions(+), 9 deletions(-) create mode 100644 .github/workflows/release.yml create mode 100644 .gitignore create mode 100644 .luacheckrc create mode 100644 .pkgmeta diff --git a/.github/workflows/release.yml b/.github/workflows/release.yml new file mode 100644 index 0000000..fa228a0 --- /dev/null +++ b/.github/workflows/release.yml @@ -0,0 +1,28 @@ +name: CI + +on: + push: + branches: + - main + tags: + - "v*" + +jobs: + build: + runs-on: ubuntu-latest + + steps: + - uses: actions/checkout@v4 + with: + fetch-depth: 0 + + - name: Run Luacheck + uses: nebularg/actions-luacheck@v1 + with: + annotate: warning + + - name: Package and Release + if: startsWith(github.ref, 'refs/tags/') + uses: BigWigsMods/packager@v2 + env: + GITHUB_OAUTH: ${{ secrets.GITHUB_TOKEN }} diff --git a/.gitignore b/.gitignore new file mode 100644 index 0000000..1cc857a --- /dev/null +++ b/.gitignore @@ -0,0 +1,2 @@ +.release/ +*.zip diff --git a/.luacheckrc b/.luacheckrc new file mode 100644 index 0000000..c8e171b --- /dev/null +++ b/.luacheckrc @@ -0,0 +1,25 @@ +std = "lua51" +max_line_length = false + +-- Globals set by this addon +globals = { + "CooldownTrackerDB", + "SLASH_COOLDOWNTRACKER1", + "SLASH_COOLDOWNTRACKER2", +} + +-- WoW API globals (read-only from this addon's perspective) +read_globals = { + -- Core API + "CreateFrame", + "GetTime", + "PlaySound", + -- Constants & tables + "SOUNDKIT", + "UIParent", + "GameTooltip", + "SlashCmdList", + -- Namespaces + "C_Timer", + "Settings", +} diff --git a/.pkgmeta b/.pkgmeta new file mode 100644 index 0000000..981e884 --- /dev/null +++ b/.pkgmeta @@ -0,0 +1,8 @@ +package-as: CooldownTracker + +ignore: + - .github + - .gitignore + - .luacheckrc + - .pkgmeta + - AGENTS.md diff --git a/AGENTS.md b/AGENTS.md index e38d18c..ad801ab 100755 --- a/AGENTS.md +++ b/AGENTS.md @@ -12,6 +12,33 @@ The addon is split into modular components, sharing a single private namespace ( - `UI.lua`: Handles rendering the main tracker window, row layouts (grid vs vertical), and the per-frame `OnUpdate` timer loop. - `Settings.lua`: Implements the in-game options panel (Escape -> Options -> AddOns) using the modern `Settings` API. Handles SavedVariables overrides. - `Core.lua`: The bootstrap file. Handles `ADDON_LOADED`, slash commands (`/cdt`), and initializes the UI and Settings. +- `.github/workflows/release.yml`: GitHub Actions CI/CD workflow (see CI/CD section below). +- `.luacheckrc`: Luacheck static analysis configuration. +- `.pkgmeta`: BigWigs packager metadata for release packaging. + +## 🔁 CI/CD +The project uses GitHub Actions for linting and release packaging. + +### Workflow (`.github/workflows/release.yml`) +- **Push to `main`:** Runs `luacheck` on all Lua files via `nebularg/actions-luacheck@v1`. +- **Push a `v*` tag:** Runs luacheck, then runs `BigWigsMods/packager@v2` which creates a GitHub Release with the addon zip attached. Uses the built-in `GITHUB_TOKEN` — no additional secrets required. + +### Luacheck (`.luacheckrc`) +- `std = "lua51"` covers standard Lua globals. +- WoW API globals (`CreateFrame`, `GetTime`, `C_Timer`, `Settings`, etc.) are declared in `read_globals`. +- Addon-owned globals (`CooldownTrackerDB`, slash command vars) are declared in `globals`. +- **When adding new WoW API calls:** if luacheck starts reporting an undefined global, add it to `read_globals` in `.luacheckrc`. + +### Packager (`.pkgmeta`) +- Dev-only files (`AGENTS.md`, `.github/`, `.luacheckrc`, `.gitignore`) are listed under `ignore` so they are excluded from the release zip. +- **When adding new dev-only files** (e.g. test scripts, editor config), add them to the `ignore` list in `.pkgmeta`. + +### Releasing +```bash +git tag -a v1.2.0 -m "Version 1.2.0" +git push origin v1.2.0 +``` +Also update `## Version:` in `CooldownTracker.toc` to match the tag before tagging. ## 📜 Coding Standards & Conventions 1. **Private Namespace:** Always use the addon's private namespace passed by the WoW client on load. Do not pollute the global environment. diff --git a/README.md b/README.md index cca0e4f..597aa42 100755 --- a/README.md +++ b/README.md @@ -18,11 +18,18 @@ Because Midnight restricts addons from reading real-time combat data, this addon ## Installation -1. Copy the `CooldownTracker` folder into: +### Download a release + +1. Go to the [Releases](../../releases) page and download the latest `CooldownTracker-*.zip`. +2. Unzip and copy the `CooldownTracker` folder into: ``` World of Warcraft\_retail_\Interface\AddOns\CooldownTracker\ ``` -2. Launch WoW and enable **Healer Cooldown Tracker** in the AddOns list. +3. Launch WoW and enable **Healer Cooldown Tracker** in the AddOns list. + +### From source + +Clone the repo and symlink (or copy) the folder directly into your AddOns directory. ## Usage @@ -70,15 +77,34 @@ No other file needs to change. ``` CooldownTracker/ -├── CooldownTracker.toc — Addon manifest & metadata -├── Data.lua — Cooldown definitions (edit this to add abilities) -├── UI.lua — Frame, row widgets, timer rendering -├── Settings.lua — In-game options panel -├── Core.lua — Init, events, slash commands -├── AGENTS.md — AI agent coding guidelines -└── README.md — This file +├── CooldownTracker.toc — Addon manifest & metadata +├── Data.lua — Cooldown definitions (edit this to add abilities) +├── UI.lua — Frame, row widgets, timer rendering +├── Settings.lua — In-game options panel +├── Core.lua — Init, events, slash commands +├── .github/workflows/release.yml — CI: luacheck on push, package+release on tag +├── .luacheckrc — Luacheck config (WoW globals whitelist) +├── .pkgmeta — BigWigs packager metadata +├── AGENTS.md — AI agent coding guidelines +└── README.md — This file +``` + +## Releases & CI + +Releases are built automatically by GitHub Actions using the [BigWigs packager](https://github.com/BigWigsMods/packager). + +- **Push to `main`** — runs [luacheck](https://github.com/mpeterv/luacheck) static analysis on all Lua files. +- **Push a version tag** — runs luacheck, packages the addon, and publishes a GitHub Release with a downloadable zip. + +To ship a release: + +```bash +git tag -a v1.2.0 -m "Version 1.2.0" +git push origin v1.2.0 ``` +The zip will appear on the [Releases](../../releases) page within a minute or two. + ## Compatibility Tested on **World of Warcraft: Midnight** (Interface 120001). Fully compliant with Midnight's addon restrictions — no combat log reading, no addon messaging. From 5b019b357e633d49d887230e7059e03564889c9f Mon Sep 17 00:00:00 2001 From: RubyJ Date: Mon, 16 Mar 2026 23:59:36 -0400 Subject: [PATCH 2/2] chore: add pull request template --- .github/pull_request_template.md | 18 ++++++++++++++++++ 1 file changed, 18 insertions(+) create mode 100644 .github/pull_request_template.md diff --git a/.github/pull_request_template.md b/.github/pull_request_template.md new file mode 100644 index 0000000..73159d0 --- /dev/null +++ b/.github/pull_request_template.md @@ -0,0 +1,18 @@ +# Summary of Changes + + + +# Testing + +_Describe how to verify this in-game, or note if the change is non-functional (CI, data, docs)._ + + + +# Checklist + +- [ ] Tested in-game on Midnight (Interface 120001) +- [ ] No new global variables introduced (or `.luacheckrc` updated if needed) +- [ ] No taint-unsafe patterns introduced (no runtime `CreateFrame`, `SetParent`, or `SetScript` on secure frames) +- [ ] `Data.lua` spell entries include both `duration` and `defaultDuration` +- [ ] New dev-only files added to `.pkgmeta` ignore list +- [ ] `## Version:` in `CooldownTracker.toc` bumped if this is a release