From 5888124bbf808c53103662cd105ff720a2e9db48 Mon Sep 17 00:00:00 2001 From: Jonathan Miller Date: Sun, 10 May 2026 20:08:44 +0000 Subject: [PATCH] docs: update WIKI_STANDARDS --- WIKI_STANDARDS.md | 203 +++++++++++++++++++++++++--------------------- 1 file changed, 112 insertions(+), 91 deletions(-) diff --git a/WIKI_STANDARDS.md b/WIKI_STANDARDS.md index 081a7a0..91c57ac 100644 --- a/WIKI_STANDARDS.md +++ b/WIKI_STANDARDS.md @@ -22,15 +22,11 @@ Brief description of what this page covers. ## Section 1 Content... -## Section 2 -Content... - --- ## Related - [Other Page](Other-Page) -- description -- [External Link](https://...) -- description --- @@ -38,7 +34,7 @@ Content... | Revision | Date | Author | Description | |---|---|---|---| -| 1.0 | YYYY-MM-DD | Author | Initial version | +| 1.0 | YYYY-MM-DD | Moko Consulting | Initial version | ``` ### Required elements @@ -48,8 +44,8 @@ Content... | Navigation link | First line | `[← Back to Home](Home)` | | H1 title | After nav | Page title matching the wiki page name | | Description | After title | 1-2 sentence summary | -| Horizontal rules | Between major sections | `---` separators for visual clarity | -| Related section | Before footer | Links to related pages and external resources | +| Horizontal rules | Between major sections | `---` separators | +| Related section | Before footer | Links to related pages | | Metadata footer | Last lines | Repo link, MokoStandards link, revision table | --- @@ -68,71 +64,40 @@ Every repo wiki must have a Home page with: | Related wikis | Recommended | Links to related project wikis | | MokoStandards backlink | Yes | Link to moko-platform wiki Home | -### Info table format - -```markdown -| Field | Value | -|---|---| -| **Type** | MCP Server / Joomla Template / Joomla Plugin / etc. | -| **Language** | PHP / TypeScript / Bash | -| **License** | GPL-3.0-or-later | -| **Platform** | [Gitea](repo-url) · [GitHub](mirror-url) | -``` - --- ## Content Guidelines ### Formatting -| Rule | Example | +| Rule | Description | |---|---| -| Use tables for structured data | Not bullet lists for key-value pairs | -| Use code blocks for commands | `` `make build` `` or fenced blocks | -| Use headers for sections | H2 for major sections, H3 for subsections | -| Use horizontal rules between sections | `---` | -| No emojis in headers | Use plain text | -| Em dashes | Use `--` not unicode `—` | +| Tables for structured data | Not bullet lists for key-value pairs | +| Code blocks with language | ` ```bash `, ` ```json `, ` ```php ` | +| Headers for sections | H2 for major, H3 for subsections | +| Horizontal rules | `---` between major sections | +| No emojis in headers | Plain text only | +| Em dashes | Use `--` not unicode | ### Writing style -- **Concise** -- lead with the answer, not the explanation -- **Scannable** -- headers, tables, and short paragraphs -- **Accurate** -- built from actual source code, not assumptions -- **Actionable** -- include commands, file paths, and examples +- **Concise** -- lead with the answer +- **Scannable** -- headers, tables, short paragraphs +- **Accurate** -- built from source code, not assumptions +- **Actionable** -- include commands, file paths, examples - **Current** -- update when code changes -### Code blocks - -Always specify the language: - -````markdown -```bash -make build -``` - -```json -{"key": "value"} -``` - -```php -$app = Factory::getApplication('site'); -``` -```` - --- ## Page Categories -Organize wiki pages into these standard categories on the Home page: - | Category | Content | |---|---| -| **Guides** | Step-by-step tutorials (Installation, Configuration, Getting Started) | -| **Reference** | Technical reference (API, Tools, CSS Variables, Endpoints) | -| **Operations** | Operational procedures (Backup, Restore, Monitoring, Troubleshooting) | -| **Architecture** | System design (Architecture, How It Works, Data Flow) | -| **Development** | Contributing (Development, Release Process, Testing) | +| **Guides** | Installation, Configuration, Getting Started | +| **Reference** | API, Tools, CSS Variables, Endpoints | +| **Operations** | Backup, Restore, Monitoring, Troubleshooting | +| **Architecture** | System design, How It Works, Data Flow | +| **Development** | Contributing, Release Process, Testing | --- @@ -140,8 +105,8 @@ Organize wiki pages into these standard categories on the Home page: | Type | Format | Example | |---|---|---| -| Guide pages | Title case, hyphenated | `Installation`, `Getting-Started` | -| Reference pages | UPPER_CASE for standards | `WIKI_STANDARDS`, `MINIFICATION` | +| Guide pages | Title case | `Installation`, `Getting-Started` | +| Reference pages | UPPER_CASE | `WIKI_STANDARDS`, `MINIFICATION` | | Technical pages | Title case | `Architecture`, `Configuration` | | Compound names | Hyphenated | `Custom-Themes`, `Backup-Recovery` | @@ -149,13 +114,7 @@ Organize wiki pages into these standard categories on the Home page: ## Metadata Footer -Every page ends with a metadata footer containing: - -1. **Repo link** -- link to the source repository -2. **MokoStandards link** -- link to the central standards wiki -3. **Revision history table** -- tracks changes to the page - -### Format +Every page ends with: ```markdown --- @@ -165,45 +124,106 @@ Every page ends with a metadata footer containing: | Revision | Date | Author | Description | |---|---|---|---| | 1.0 | 2026-05-09 | Moko Consulting | Initial version | -| 1.1 | 2026-05-10 | Moko Consulting | Added troubleshooting section | ``` -### Rules - -- Increment minor version for content updates (1.0 → 1.1) -- Increment major version for restructuring (1.x → 2.0) -- Author is always "Moko Consulting" for org work -- Date is ISO format (YYYY-MM-DD) - --- -## Wiki Health Requirements +## Required Repository Files -The `check_wiki_health.php` validation checks: +Per the repo health check (`check_repo_health.php`), every repo must have: -| Check | Requirement | +### Required (positive points) + +| File | Points | Purpose | +|---|---|---| +| `README.md` | 8 | Project overview (mirrors wiki Home) | +| `LICENSE` | 8 | GPL-3.0-or-later | +| `CHANGELOG.md` | 5 | Release history with [Unreleased] section | +| `CLAUDE.md` | 5 | Claude Code context (project overview, commands, architecture, rules) | +| `CONTRIBUTING.md` | 4 | Contribution guidelines | +| `SECURITY.md` | 4 | Security policy | +| `.gitignore` | 3 | Must include: `.claude/`, `TODO.md`, `*.min.css`, `*.min.js` | +| `Makefile` | 3 | Build targets (minify, build, release) | + +### Disallowed (flagged if present) + +| File | Reason | |---|---| -| Home page exists | Required | -| MokoStandards backlink | Required on Home page | -| Page count | At least 1 (Home) | -| Navigation links | `[← Back to Home](Home)` on all non-Home pages | -| Metadata footer | Repo link + revision table on all pages | +| `TODO.md` | Use issue tracker, not committed files | +| `.claude/` | Local workspace config | +| `.mcp.json` | Local MCP config | +| `renovate.json` | Removed from ecosystem | +| `profile.ps1` | Local PowerShell profile | +| `vendor/` | Install via composer, don't commit | +| `node_modules/` | Install via npm, don't commit | +| `.env` / `credentials.json` | Secrets never committed | + +### Manifest + +Every repo must have `.gitea/.moko-platform` XML manifest with: +- Identity (name, org, description, license) +- Governance (platform type, standards version) +- Build (language, package type, entry point) + +--- + +## CLAUDE.md Standard + +Every repo must have a `CLAUDE.md` that provides context to Claude Code: + +```markdown +# CLAUDE.md + +This file provides guidance to Claude Code when working with this repository. + +## Project Overview +**RepoName** -- description + +| Field | Value | +|---|---| +| **Platform** | joomla / dolibarr / mcp-server / client / template / generic | +| **Language** | PHP / TypeScript / Shell | +| **Default branch** | main or dev | +| **Wiki** | [Wiki link](wiki-url) | +| **Standards** | [MokoStandards](moko-platform-wiki-url) | + +## Common Commands +(make targets, npm scripts, composer commands) + +## Architecture +(key directories and files for this platform type) + +## Rules +- Never commit .claude/, .mcp.json, TODO.md, *.min.css/js +- Attribution: Authored-by: Moko Consulting +- Branch strategy: dev → main +- Standards: MokoStandards +``` + +--- + +## Repo Health Check + +The `check_repo_health.php` script validates repos against these standards: + +| Category | Points | Checks | +|---|---|---| +| Required Files | 40 | README, LICENSE, CHANGELOG, CONTRIBUTING, SECURITY, CLAUDE.md, .gitignore, Makefile | +| Manifest & Config | 20 | .moko-platform, workflows, README quality, .gitignore content, CLAUDE.md quality | +| Documentation | 15 | No docs/ (wiki-first), CHANGELOG [Unreleased] | +| Disallowed | 10 | No TODO.md, vendor/, node_modules/, .claude/, .mcp.json, renovate.json, profile.ps1 | +| Workflows | 15 | repo-health, sync-roadmap-wiki, CI/deploy | +| Security | 20 | SECURITY.md, scanning workflow, no renovate.json, no secrets | +| Rulesets | 15 | Main protected, dev branch, branch protections | +| Deployment | 10 | Deploy workflow, build system | + +Threshold: 70% to pass. --- ## GitHub Mirror -All wikis are backed up daily to [mokoconsulting-tech/wiki](https://github.com/mokoconsulting-tech/wiki) on GitHub via `sync-wikis-to-github.sh` (runs daily at 5am UTC). - -Structure: -``` -wiki/ - README.md (auto-generated index) - moko-platform/ (30+ pages) - MokoOnyx/ (9 pages) - monitor-mcp/ (6 pages) - ... -``` +All wikis are backed up daily to [mokoconsulting-tech/wiki](https://github.com/mokoconsulting-tech/wiki) on GitHub via `sync-wikis-to-github.sh` (runs daily at 5am UTC). Auto-discovers all repos with wikis across all orgs. --- @@ -219,4 +239,5 @@ wiki/ | Revision | Date | Author | Description | |---|---|---|---| -| 1.0 | 2026-05-09 | Moko Consulting | Initial wiki standards document | +| 1.0 | 2026-05-09 | Moko Consulting | Initial wiki standards | +| 2.0 | 2026-05-10 | Moko Consulting | Added CLAUDE.md standard, repo health check details, required/disallowed files |