From f678508f8aba7d776d0c1f8d20c0f02bfec30309 Mon Sep 17 00:00:00 2001 From: Jonathan Miller <230051081+jmiller-moko@users.noreply.github.com> Date: Thu, 9 Apr 2026 10:51:10 -0500 Subject: [PATCH] chore: update .github/CLAUDE.md from MokoStandards --- .github/CLAUDE.md | 372 +++++++++++++++++++++------------------------- 1 file changed, 171 insertions(+), 201 deletions(-) diff --git a/.github/CLAUDE.md b/.github/CLAUDE.md index 4e7b705..df7d501 100644 --- a/.github/CLAUDE.md +++ b/.github/CLAUDE.md @@ -1,22 +1,3 @@ - - > [!IMPORTANT] > **πŸ”§ AI Self-Update Required on First Use** > @@ -38,34 +19,135 @@ NOTE: Synced to .github/copilot-instructions.md in all Joomla/WaaS repos via bul > |---|---| > | `MokoCassiopeia` | The GitHub repository name (visible in the URL, `README.md` heading, or `git remote -v`) | > | `https://github.com/mokoconsulting-tech/MokoCassiopeia` | Full GitHub URL, e.g. `https://github.com/mokoconsulting-tech/` | +> | `A modern enhancement layer for Joomla’s Cassiopeia template. MokoCassiopeia adds Font Awesome 7, Bootstrap 5 helpers, an automatic Table of Contents (TOC) utility, and optional expansions including Google Tag Manager and Google Analytics (GA4) hooks.` | First paragraph of `README.md` body, or the GitHub repo description | > | `{{EXTENSION_NAME}}` | The `` element in `manifest.xml` at the repository root | > | `{{EXTENSION_TYPE}}` | The `type` attribute of the `` tag in `manifest.xml` (`component`, `module`, `plugin`, or `template`) | > | `{{EXTENSION_ELEMENT}}` | The `` tag in `manifest.xml`, or the filename prefix (e.g. `com_myextension`, `mod_mymodule`) | > > --- -# MokoCassiopeia β€” GitHub Copilot Custom Instructions +# What This Repo Is -## What This Repo Is +**MokoCassiopeia** is a Moko Consulting **MokoWaaS** (Joomla) extension repository. -This is a **Moko Consulting MokoWaaS** (Joomla) repository governed by [MokoStandards](https://github.com/mokoconsulting-tech/MokoStandards). All coding standards, workflows, and policies are defined there and enforced here via bulk sync. +A modern enhancement layer for Joomla’s Cassiopeia template. MokoCassiopeia adds Font Awesome 7, Bootstrap 5 helpers, an automatic Table of Contents (TOC) utility, and optional expansions including Google Tag Manager and Google Analytics (GA4) hooks. -Repository URL: https://github.com/mokoconsulting-tech/MokoCassiopeia Extension name: **{{EXTENSION_NAME}}** Extension type: **{{EXTENSION_TYPE}}** (`{{EXTENSION_ELEMENT}}`) -Platform: **Joomla 4.x / MokoWaaS** +Repository URL: https://github.com/mokoconsulting-tech/MokoCassiopeia + +This repository is governed by [MokoStandards](https://github.com/mokoconsulting-tech/MokoStandards) β€” the single source of truth for coding standards, file-header policies, GitHub Actions workflows, and Terraform configuration templates across all Moko Consulting repositories. --- -## Primary Language +# Repo Structure -**PHP** (β‰₯ 7.4) is the primary language for this Joomla extension. JavaScript may be used for frontend enhancements. YAML uses 2-space indentation. All other text files use tabs per `.editorconfig`. +``` +MokoCassiopeia/ +β”œβ”€β”€ manifest.xml # Joomla installer manifest (root β€” required) +β”œβ”€β”€ update.xml # Update server manifest (root β€” required) +β”œβ”€β”€ site/ # Frontend (site) code +β”‚ β”œβ”€β”€ controller.php +β”‚ β”œβ”€β”€ controllers/ +β”‚ β”œβ”€β”€ models/ +β”‚ └── views/ +β”œβ”€β”€ admin/ # Backend (admin) code +β”‚ β”œβ”€β”€ controller.php +β”‚ β”œβ”€β”€ controllers/ +β”‚ β”œβ”€β”€ models/ +β”‚ β”œβ”€β”€ views/ +β”‚ └── sql/ +β”œβ”€β”€ language/ # Language INI files +β”œβ”€β”€ media/ # CSS, JS, images +β”œβ”€β”€ docs/ # Technical documentation +β”œβ”€β”€ tests/ # Test suite +β”œβ”€β”€ .github/ +β”‚ β”œβ”€β”€ workflows/ # CI/CD workflows (synced from MokoStandards) +β”‚ β”œβ”€β”€ copilot-instructions.md +β”‚ └── CLAUDE.md # This file +β”œβ”€β”€ README.md # Version source of truth +β”œβ”€β”€ CHANGELOG.md +β”œβ”€β”€ CONTRIBUTING.md +└── LICENSE # GPL-3.0-or-later +``` --- -## File Header β€” Always Required on New Files +# Primary Language -Every new file needs a copyright header as its first content. +**PHP** (β‰₯ 7.4) is the primary language for this Joomla extension. YAML uses 2-space indentation. All other text files use tabs per `.editorconfig`. + +--- + +# Version Management + +**`README.md` is the single source of truth for the repository version.** + +- **Bump the patch version on every PR** β€” increment `XX.YY.ZZ` (e.g. `01.02.03` β†’ `01.02.04`) in `README.md` before opening the PR; the `sync-version-on-merge` workflow propagates it to all `FILE INFORMATION` headers automatically on merge. +- Version format is zero-padded semver: `XX.YY.ZZ` (e.g. `01.02.03`). +- Never hardcode a version number in body text β€” use the badge or FILE INFORMATION header only. + +### Joomla Version Alignment + +Three files must **always have the same version**: + +| File | Where the version lives | +|------|------------------------| +| `README.md` | `FILE INFORMATION` block + badge | +| `manifest.xml` | `` tag | +| `update.xml` | `` in the most recent `` block | + +The `make release` command / release workflow syncs all three automatically. + +--- + +# update.xml β€” Required in Repo Root + +`update.xml` is the Joomla update server manifest. It allows Joomla installations to check for new versions of this extension via: + +```xml + + + + https://github.com/mokoconsulting-tech/MokoCassiopeia/raw/main/update.xml + + +``` + +**Rules:** +- Every release prepends a new `` block at the top β€” older entries are preserved. +- `` in `update.xml` must exactly match `` in `manifest.xml` and `README.md`. +- `` must be a publicly accessible GitHub Releases asset URL. +- `` β€” backslash is literal (Joomla regex syntax). + +Example `update.xml` entry for a new release: +```xml + + + {{EXTENSION_NAME}} + MokoCassiopeia + {{EXTENSION_ELEMENT}} + {{EXTENSION_TYPE}} + 01.02.04 + https://github.com/mokoconsulting-tech/MokoCassiopeia/releases/tag/01.02.04 + + + https://github.com/mokoconsulting-tech/MokoCassiopeia/releases/download/01.02.04/{{EXTENSION_ELEMENT}}-01.02.04.zip + + + + 7.4 + Moko Consulting + https://mokoconsulting.tech + + +``` + +--- + +# File Header Requirements + +Every new file **must** have a copyright header as its first content. JSON files, binary files, generated files, and third-party files are exempt. **PHP:** ```php @@ -80,141 +162,47 @@ Every new file needs a copyright header as its first content. * DEFGROUP: MokoCassiopeia.{{EXTENSION_TYPE}} * INGROUP: MokoCassiopeia * REPO: https://github.com/mokoconsulting-tech/MokoCassiopeia - * PATH: /path/to/file.php + * PATH: /site/controllers/item.php * VERSION: XX.YY.ZZ - * BRIEF: One-line description of purpose + * BRIEF: One-line description of file purpose */ defined('_JEXEC') or die; ``` -**Markdown:** -```markdown - -``` - -**YAML / Shell / XML:** Use the appropriate comment syntax with the same fields. JSON files are exempt. +**Markdown / YAML / Shell / XML:** Use the appropriate comment syntax with the same fields. --- -## Version Management +# Coding Standards -**`README.md` is the single source of truth for the repository version.** +## Naming Conventions -- **Bump the patch version on every PR** β€” increment `XX.YY.ZZ` (e.g. `01.02.03` β†’ `01.02.04`) in `README.md` before opening the PR; the `sync-version-on-merge` workflow propagates it automatically to all badges and `FILE INFORMATION` headers on merge to `main`. -- The `VERSION: XX.YY.ZZ` field in `README.md` governs all other version references. -- Version format is zero-padded semver: `XX.YY.ZZ` (e.g. `01.02.03`). -- Never hardcode a specific version in document body text β€” use the badge or FILE INFORMATION header only. +| Context | Convention | Example | +|---------|-----------|---------| +| PHP class | `PascalCase` | `ItemModel` | +| PHP method / function | `camelCase` | `getItems()` | +| PHP variable | `$snake_case` | `$item_id` | +| PHP constant | `UPPER_SNAKE_CASE` | `MAX_ITEMS` | +| PHP class file | `PascalCase.php` | `ItemModel.php` | +| YAML workflow | `kebab-case.yml` | `ci-joomla.yml` | +| Markdown doc | `kebab-case.md` | `installation-guide.md` | -### Joomla Version Alignment +## Commit Messages -The version in `README.md` **must always match** the `` tag in `manifest.xml` and the latest entry in `updates.xml`. The `make release` command / release workflow updates all three automatically. +Format: `(): ` β€” imperative, lower-case subject, no trailing period. -```xml - -01.02.04 +Valid types: `feat` Β· `fix` Β· `docs` Β· `chore` Β· `ci` Β· `refactor` Β· `style` Β· `test` Β· `perf` Β· `revert` Β· `build` - - - - {{EXTENSION_NAME}} - 01.02.04 - - - https://github.com/mokoconsulting-tech/MokoCassiopeia/releases/download/01.02.04/{{EXTENSION_ELEMENT}}-01.02.04.zip - - - - - - -``` +## Branch Naming + +Format: `/[/description]` + +Approved prefixes: `dev/` Β· `rc/` Β· `version/` Β· `patch/` Β· `copilot/` Β· `dependabot/` --- -## Joomla Extension Structure - -``` -MokoCassiopeia/ -β”œβ”€β”€ manifest.xml # Joomla installer manifest (root β€” required) -β”œβ”€β”€ updates.xml # Update server manifest (root β€” required, see below) -β”œβ”€β”€ site/ # Frontend (site) code -β”‚ β”œβ”€β”€ controller.php -β”‚ β”œβ”€β”€ controllers/ -β”‚ β”œβ”€β”€ models/ -β”‚ └── views/ -β”œβ”€β”€ admin/ # Backend (admin) code -β”‚ β”œβ”€β”€ controller.php -β”‚ β”œβ”€β”€ controllers/ -β”‚ β”œβ”€β”€ models/ -β”‚ β”œβ”€β”€ views/ -β”‚ └── sql/ -β”œβ”€β”€ language/ # Language INI files -β”œβ”€β”€ media/ # CSS, JS, images (deployed to /media/{{EXTENSION_ELEMENT}}/) -β”œβ”€β”€ docs/ # Technical documentation -β”œβ”€β”€ tests/ # Test suite -β”œβ”€β”€ .github/ -β”‚ β”œβ”€β”€ workflows/ -β”‚ β”œβ”€β”€ copilot-instructions.md # This file -β”‚ └── CLAUDE.md -β”œβ”€β”€ README.md # Version source of truth -β”œβ”€β”€ CHANGELOG.md -β”œβ”€β”€ CONTRIBUTING.md -β”œβ”€β”€ LICENSE # GPL-3.0-or-later -└── Makefile # Build automation -``` - ---- - -## updates.xml β€” Required in Repo Root - -`updates.xml` **must exist at the repository root**. It is the Joomla update server manifest that allows Joomla installations to check for new versions of this extension. - -The `manifest.xml` must reference it via: -```xml - - - https://github.com/mokoconsulting-tech/MokoCassiopeia/raw/main/updates.xml - - -``` - -**Rules:** -- Every release must prepend a new `` block at the top of `updates.xml` β€” old entries must be preserved below. -- The `` in `updates.xml` must exactly match `` in `manifest.xml` and the version in `README.md`. -- The `` must be a publicly accessible direct download link (GitHub Releases asset URL). -- `` β€” the backslash is a **literal backslash character** in the XML attribute value; Joomla's update-server parser treats the value as a regular expression, so `\.` matches a literal dot and `[0-9]+` matches one or more digits. Do not double-escape it. - ---- - -## manifest.xml Rules - -- Lives at the repo root as `manifest.xml` (not inside `site/` or `admin/`). -- `` tag must be kept in sync with `README.md` version and `updates.xml`. -- Must include `` block pointing to this repo's `updates.xml`. -- Must include `` and `` sections. -- Joomla 4.x requires `Moko\{{EXTENSION_NAME}}` for namespaced extensions. - ---- - -## GitHub Actions β€” Token Usage +# GitHub Actions β€” Token Usage Every workflow must use **`secrets.GH_TOKEN`** (the org-level Personal Access Token). @@ -229,76 +217,58 @@ env: ``` ```yaml -# ❌ Wrong β€” never use these in workflows +# ❌ Wrong β€” never use these token: ${{ github.token }} token: ${{ secrets.GITHUB_TOKEN }} ``` --- -## MokoStandards Reference - -This repository is governed by [MokoStandards](https://github.com/mokoconsulting-tech/MokoStandards). Authoritative policies: - -| Document | Purpose | -|----------|---------| -| [file-header-standards.md](https://github.com/mokoconsulting-tech/MokoStandards/blob/main/docs/policy/file-header-standards.md) | Copyright-header rules for every file type | -| [coding-style-guide.md](https://github.com/mokoconsulting-tech/MokoStandards/blob/main/docs/policy/coding-style-guide.md) | Naming and formatting conventions | -| [branching-strategy.md](https://github.com/mokoconsulting-tech/MokoStandards/blob/main/docs/policy/branching-strategy.md) | Branch naming, hierarchy, and release workflow | -| [merge-strategy.md](https://github.com/mokoconsulting-tech/MokoStandards/blob/main/docs/policy/merge-strategy.md) | Squash-merge policy and PR title/body conventions | -| [changelog-standards.md](https://github.com/mokoconsulting-tech/MokoStandards/blob/main/docs/policy/changelog-standards.md) | How and when to update CHANGELOG.md | -| [joomla-development-guide.md](https://github.com/mokoconsulting-tech/MokoStandards/blob/main/docs/guide/waas/joomla-development-guide.md) | MokoWaaS Joomla extension development guide | - ---- - -## Naming Conventions - -| Context | Convention | Example | -|---------|-----------|---------| -| PHP class | `PascalCase` | `MyController` | -| PHP method / function | `camelCase` | `getItems()` | -| PHP variable | `$snake_case` | `$item_id` | -| PHP constant | `UPPER_SNAKE_CASE` | `MAX_ITEMS` | -| PHP class file | `PascalCase.php` | `ItemModel.php` | -| YAML workflow | `kebab-case.yml` | `ci-joomla.yml` | -| Markdown doc | `kebab-case.md` | `installation-guide.md` | - ---- - -## Commit Messages - -Format: `(): ` β€” imperative, lower-case subject, no trailing period. - -Valid types: `feat` Β· `fix` Β· `docs` Β· `chore` Β· `ci` Β· `refactor` Β· `style` Β· `test` Β· `perf` Β· `revert` Β· `build` - ---- - -## Branch Naming - -Format: `/[/description]` - -Approved prefixes: `dev/` Β· `rc/` Β· `version/` Β· `patch/` Β· `copilot/` Β· `dependabot/` - ---- - -## Keeping Documentation Current +# Keeping Documentation Current | Change type | Documentation to update | |-------------|------------------------| | New or renamed PHP class/method | PHPDoc block; `docs/api/` entry | -| New or changed manifest.xml | Update `updates.xml` version; bump README.md version | -| New release | Prepend `` block to `updates.xml`; update CHANGELOG.md; bump README.md version | +| New or changed `manifest.xml` | Sync version to `update.xml` and `README.md` | +| New release | Prepend `` to `update.xml`; update `CHANGELOG.md`; bump `README.md` | | New or changed workflow | `docs/workflows/.md` | | Any modified file | Update the `VERSION` field in that file's `FILE INFORMATION` block | | **Every PR** | **Bump the patch version** β€” increment `XX.YY.ZZ` in `README.md`; `sync-version-on-merge` propagates it | --- -## Key Constraints +# What NOT to Do -- Never commit directly to `main` β€” all changes go via PR, squash-merged -- Never skip the FILE INFORMATION block on a new file -- Never add `defined('_JEXEC') or die;` to CLI scripts or model tests β€” only to web-accessible PHP files -- Never hardcode version numbers in body text β€” update `README.md` and let automation propagate -- Never use `github.token` or `secrets.GITHUB_TOKEN` in workflows β€” always use `secrets.GH_TOKEN` -- Never let `manifest.xml` version, `updates.xml` version, and `README.md` version go out of sync +- **Never commit directly to `main`** β€” all changes go through a PR. +- **Never hardcode version numbers** in body text β€” update `README.md` and let automation propagate. +- **Never let `manifest.xml`, `update.xml`, and `README.md` versions diverge.** +- **Never skip the FILE INFORMATION block** on a new source file. +- **Never use bare `catch (\Throwable $e) {}`** β€” always log or re-throw. +- **Never mix tabs and spaces** within a file β€” follow `.editorconfig`. +- **Never use `github.token` or `secrets.GITHUB_TOKEN` in workflows** β€” always use `secrets.GH_TOKEN`. +- **Never remove `defined('_JEXEC') or die;`** from web-accessible PHP files. + +--- + +# PR Checklist + +Before opening a PR, verify: + +- [ ] Patch version bumped in `README.md` (e.g. `01.02.03` β†’ `01.02.04`) +- [ ] If this is a release: `manifest.xml` version updated; `update.xml` updated with new entry +- [ ] FILE INFORMATION headers updated in modified files +- [ ] CHANGELOG.md updated +- [ ] Tests pass + +--- + +# Key Policy Documents (MokoStandards) + +| Document | Purpose | +|----------|---------| +| [file-header-standards.md](https://github.com/mokoconsulting-tech/MokoStandards/blob/main/docs/policy/file-header-standards.md) | Copyright-header rules for every file type | +| [coding-style-guide.md](https://github.com/mokoconsulting-tech/MokoStandards/blob/main/docs/policy/coding-style-guide.md) | Naming and formatting conventions | +| [branching-strategy.md](https://github.com/mokoconsulting-tech/MokoStandards/blob/main/docs/policy/branching-strategy.md) | Branch naming, hierarchy, and release workflow | +| [merge-strategy.md](https://github.com/mokoconsulting-tech/MokoStandards/blob/main/docs/policy/merge-strategy.md) | Squash-merge policy and PR conventions | +| [changelog-standards.md](https://github.com/mokoconsulting-tech/MokoStandards/blob/main/docs/policy/changelog-standards.md) | How and when to update CHANGELOG.md | +| [joomla-development-guide.md](https://github.com/mokoconsulting-tech/MokoStandards/blob/main/docs/guide/waas/joomla-development-guide.md) | MokoWaaS Joomla extension development guide | \ No newline at end of file