Public Access
jmiller
d736df870a
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>
140 lines
5.9 KiB
Markdown
140 lines
5.9 KiB
Markdown
<!--
|
|
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
|
|
-->
|
|
|
|
[](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)
|