From d736df870a59aa77a601f65da99e08b9d9496c72 Mon Sep 17 00:00:00 2001 From: jmiller Date: Wed, 22 Apr 2026 09:01:56 +0000 Subject: [PATCH] docs: add client repository standards documentation Covers naming conventions, directory structure, privacy rules, workflow profile, update server priority, deployment methods, and differences from standard Joomla repos. Co-Authored-By: Claude Opus 4.6 (1M context) --- docs/client-repos.md | 139 ++++++++++++++++++++++++++++++++++++++++ docs/workflows/index.md | 4 ++ 2 files changed, 143 insertions(+) create mode 100644 docs/client-repos.md diff --git a/docs/client-repos.md b/docs/client-repos.md new file mode 100644 index 0000000..9e5b415 --- /dev/null +++ b/docs/client-repos.md @@ -0,0 +1,139 @@ + + +[![MokoStandards](https://img.shields.io/badge/MokoStandards-04.06.00-orange)](https://git.mokoconsulting.tech/MokoConsulting/MokoStandards) + +# Client Repository Standards + +## Overview + +Client repos (`client-*`) contain Joomla site customizations for individual clients — templates, overrides, custom CSS, module configurations, and deployment scripts. They follow the **Joomla** workflow profile but have additional rules around privacy, branding, and deployment. + +## Naming Convention + +``` +client-{clientname} +``` + +- Lowercase, hyphenated client identifier +- No version numbers in the repo name +- Examples: `client-clarksvillefurs`, `client-kiddieland`, `client-vexcreations` + +## Repository Structure + +``` +client-{name}/ +├── .github/ # Workflows, CLAUDE.md, CODEOWNERS +│ ├── workflows/ # Standard Joomla workflows (from template) +│ ├── CLAUDE.md # AI assistant context for this client +│ └── CODEOWNERS # jmiller owns all files +├── src/ # Joomla extension source +│ ├── templates/ # Template overrides +│ ├── modules/ # Custom modules +│ ├── plugins/ # Custom plugins +│ └── media/ # CSS, JS, images +├── docs/ # Client-specific documentation +│ ├── INSTALLATION.md # Deployment instructions +│ └── update-server.md # Update server configuration +├── scripts/ # Build and deployment scripts +├── updates.xml # Joomla update server manifest +├── composer.json # Dependencies +├── CHANGELOG.md # Version history +├── README.md # Client overview (no sensitive details) +├── LICENSE # GPL-3.0-or-later +└── Makefile # Build targets +``` + +## Privacy Rules + +Client repos are **private** by default. These rules are non-negotiable: + +1. **No client credentials** in the repo — passwords, API keys, FTP credentials, database passwords go in environment variables or secure secrets, never in code or config files +2. **No PII** — no customer names, emails, addresses, phone numbers in code or comments +3. **No client-specific hostnames** in committed configs — use environment variables or `sftp-config.json.template` patterns with placeholders +4. **README.md is generic** — describes the extension type, not the client's business details +5. **CLAUDE.md may reference the client** by name for AI context, but must not include credentials + +## Workflows + +Client repos use the **Joomla workflow profile** from `MokoStandards-Template-Client`: + +- `auto-assign.yml` — Auto-assign issues/PRs to jmiller +- `auto-dev-issue.yml` — Create tracking issue on dev branch push +- `auto-release.yml` — Create GitHub Release on main merge +- `changelog-validation.yml` — Validate CHANGELOG.md format +- `ci-joomla.yml` — Joomla manifest validation, XML lint +- `codeql-analysis.yml` — Security scanning +- `copilot-agent.yml` — Copilot agent configuration +- `deploy-manual.yml` — Manual FTP deploy for testing +- `enterprise-firewall-setup.yml` — Copilot firewall rules +- `project-setup.yml` — Initialize project structure +- `repo_health.yml` — Repository health checks +- `repository-cleanup.yml` — Clean up stale branches/artifacts +- `standards-compliance.yml` — MokoStandards validation +- `sync-version-on-merge.yml` — Version tracking +- `update-docs.yml` — Auto-update documentation indexes +- `update-server.yml` — Update `updates.xml` on release + +## Release Tags + +Standard 5-tag system applies: + +- `development` — Dev builds +- `alpha` — Internal testing +- `beta` — Client preview / UAT +- `release-candidate` — Final QA before production +- `stable` — Production release + +## Update Server + +Client repos use the standard dual update server with **Gitea as priority 1**: + +```xml + + + https://git.mokoconsulting.tech/MokoConsulting/client-{name}/raw/branch/main/updates.xml + + + https://raw.githubusercontent.com/mokoconsulting-tech/client-{name}/main/updates.xml + + +``` + +## Deployment + +Client sites are deployed via: + +1. **Joomla updater** — site pulls from `updates.xml` (preferred for production) +2. **Manual FTP** — via `deploy-manual.yml` workflow dispatch (for dev/staging) +3. **Direct install** — download ZIP from GitHub Release and install via Joomla admin + +## Creating a New Client Repo + +1. Create from template: `MokoStandards-Template-Client` +2. Name it `client-{clientname}` (lowercase, hyphenated) +3. Set repo to **private** +4. Set up secrets: `GA_TOKEN`, `GH_TOKEN` +5. Configure push mirror to GitHub +6. Apply branch protection on `main` +7. Update `README.md`, `composer.json`, `CLAUDE.md` with client-specific context +8. Run initial bulk sync to pull latest standards + +## Differences from Standard Joomla Repos + +- **Visibility**: Always private (standard Joomla repos can be public) +- **Template**: `MokoStandards-Template-Client` (not `Template-Joomla-*`) +- **Extra workflows**: `project-setup.yml`, `update-docs.yml`, `copilot-agent.yml` +- **SFTP config**: `sftp-config.json.template` with credential placeholders +- **Branding**: Client-specific (not Moko Consulting) +- **Deployment**: Joomla updater + manual FTP (standard repos use updater only) diff --git a/docs/workflows/index.md b/docs/workflows/index.md index 71faf88..9bdafb7 100644 --- a/docs/workflows/index.md +++ b/docs/workflows/index.md @@ -29,6 +29,10 @@ Joomla repos use GitHub Release ZIPs via `auto-release.yml` + `updates.xml`. No - [Changelog Management](./changelog-management.md) — automated changelog generation - [Changelog Validation](./changelog-validation.md) — validates CHANGELOG.md format on PR +## Client Repositories + +- [Client Repo Standards](../client-repos.md) — naming, privacy, structure, deployment for client-* repos + ## CI & Compliance Workflows - [CI Joomla](./ci-joomla.md) — Joomla-specific CI checks (manifest validation, language files, XML lint)