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) <noreply@anthropic.com>
2026-04-22 09:01:56 +00:00
parent 3e15d4d3b0
commit d736df870a
2 changed files with 143 additions and 0 deletions
@@ -0,0 +1,139 @@
+<!--
+Copyright (C) 2026 Moko Consulting <hello@mokoconsulting.tech>
+SPDX-License-Identifier: GPL-3.0-or-later
+
+# FILE INFORMATION
+DEFGROUP: MokoStandards.Documentation
+INGROUP: MokoStandards.ClientRepos
+REPO: https://git.mokoconsulting.tech/MokoConsulting/MokoStandards-API
+PATH: /docs/client-repos.md
+VERSION: 04.06.00
+BRIEF: Standards and conventions for client-facing Joomla site repositories
+-->
+
+[![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
+<updateservers>
+  <server type="extension" priority="1" name="{ExtName} (Gitea)">
+    https://git.mokoconsulting.tech/MokoConsulting/client-{name}/raw/branch/main/updates.xml
+  </server>
+  <server type="extension" priority="2" name="{ExtName} (GitHub)">
+    https://raw.githubusercontent.com/mokoconsulting-tech/client-{name}/main/updates.xml
+  </server>
+</updateservers>
+```
+
+## 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)
@@ -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)