From fa233787b02212419933ee06929f6789b415be36 Mon Sep 17 00:00:00 2001 From: "gitea-actions[bot]" Date: Tue, 12 May 2026 05:01:15 +0000 Subject: [PATCH] docs: sync wikis from Gitea (2026-05-12 05:01 UTC) --- MokoOnyx/Roadmap.md | 23 + MokoWaaS/guides-build-guide.-.-.md | 8 +- README.md | 80 +- moko-platform/ARCHITECTURE.md | 16 +- moko-platform/AUTO_CREATE_ORG_PROJECTS.md | 13 + moko-platform/DRY_RUN_PATTERN.md | 13 + moko-platform/Documentation-Standards.-.-.md | 17 +- moko-platform/Documentation-Standards.-.md | 13 + moko-platform/File-Header-Standards.-.md | 139 ++ moko-platform/Home.md | 1 + moko-platform/JOOMLA_SYNC.md | 13 + .../LEGAL_DOC_GENERATOR_WEB_README.md | 13 + moko-platform/MCP-Servers.-.-.-.md | 13 + moko-platform/MINIFICATION.md | 9 +- moko-platform/NEW_SCRIPTS.md | 25 +- moko-platform/QUICKSTART_ORG_PROJECTS.md | 13 + moko-platform/SITE_MONITORING.md | 13 + moko-platform/WIKI_STANDARDS.md | 36 +- moko-platform/WORKFLOW_STANDARDS.md | 33 +- moko-platform/api-automation-index.-.-.md | 21 +- .../api-definitions-default-index.-.-.md | 15 +- .../api-definitions-sync-index.-.-.md | 15 +- moko-platform/api-deploy-index.-.-.md | 21 +- moko-platform/api-fix-index.-.-.md | 21 +- moko-platform/api-index.-.-.md | 15 +- moko-platform/api-maintenance-index.-.-.md | 21 +- moko-platform/api-plugin-index.-.-.md | 21 +- moko-platform/api-tests-index.-.-.md | 15 +- moko-platform/api-tests-sample-index.-.-.md | 15 +- moko-platform/api-validate-index.-.-.md | 21 +- moko-platform/automation-README.-.-.md | 281 ++-- ...utomation-branch-version-automation.-.-.md | 683 +++++----- moko-platform/automation-push-files.-.-.md | 15 +- moko-platform/automation-repo-cleanup.-.-.md | 15 +- moko-platform/client-repos.-.-.-.md | 13 + .../standards-mokostandards-file-spec.-.-.md | 13 + moko-platform/workflows-README.-.-.md | 125 +- moko-platform/workflows-auto-release.-.-.md | 187 +-- .../workflows-branch-protection.-.-.md | 433 +++--- moko-platform/workflows-build-release.-.-.md | 13 + moko-platform/workflows-cascade-dev.-.-.md | 427 +++--- .../workflows-changelog-management.-.-.md | 649 ++++----- .../workflows-demo-deployment.-.-.md | 15 +- .../workflows-dev-branch-tracking.-.-.md | 15 +- moko-platform/workflows-dev-deployment.-.-.md | 17 +- moko-platform/workflows-index.-.-.md | 157 ++- moko-platform/workflows-release-system.-.-.md | 405 +++--- moko-platform/workflows-renovate.-.-.md | 149 ++- .../workflows-reusable-workflows.-.-.md | 1113 ++++++++-------- moko-platform/workflows-rs-deployment.-.-.md | 65 +- .../workflows-secret-scanning.-.-.md | 129 +- .../workflows-shared-workflows.-.-.md | 17 +- .../workflows-standards-compliance.-.-.md | 1185 +++++++++-------- .../workflows-static-analysis.-.-.md | 116 +- .../workflows-workflow-architecture.-.-.md | 98 +- 55 files changed, 3854 insertions(+), 3173 deletions(-) create mode 100644 MokoOnyx/Roadmap.md create mode 100644 moko-platform/File-Header-Standards.-.md diff --git a/MokoOnyx/Roadmap.md b/MokoOnyx/Roadmap.md new file mode 100644 index 0000000..65a6c4e --- /dev/null +++ b/MokoOnyx/Roadmap.md @@ -0,0 +1,23 @@ +# Roadmap + +> Auto-generated from project milestones and issues. +> Last updated: 2026-05-11 17:09 UTC + +## Active Milestones + +_No active milestones._ + +## Backlog + +_Issues not yet assigned to a milestone._ + +- [ ] feat: AI-generated page layouts from text prompts (#21) `type: feature` +- [ ] feat: Visual page builder with drag-and-drop (#20) `type: feature` +- [ ] feat: Export/import themes (#19) `type: feature` +- [ ] feat: CSS variable editor (#18) `type: feature` +- [ ] feat: Theme presets (#17) `type: feature` +- [ ] feat: Live preview customizer (#16) `type: feature` +- [ ] bug: site.webmanifest 404 — favicon generator not creating manifest (#1) + +--- +_Generated by [sync-roadmap-wiki](https://git.mokoconsulting.tech/MokoConsulting/MokoOnyx/actions) workflow._ diff --git a/MokoWaaS/guides-build-guide.-.-.md b/MokoWaaS/guides-build-guide.-.-.md index 3fdeb57..ec4f187 100644 --- a/MokoWaaS/guides-build-guide.-.-.md +++ b/MokoWaaS/guides-build-guide.-.-.md @@ -56,7 +56,7 @@ mokowaas/ │ ├── verify_changelog.sh │ └── update_changelog.sh │ - └── .mokogitea/ (CI/CD workflows) + └── .github/ (CI/CD workflows) └── workflows/*.yml ``` @@ -119,7 +119,7 @@ For a version to qualify as release ready: ## 6. Automated Build Options -Automated build and validation can be handled via configured CI workflows (for example, `.mokogitea/workflows/build.yml`) or other non-interactive tooling maintained in the repository. This keeps build behavior consistent across environments and reduces manual intervention. +Automated build and validation can be handled via configured CI workflows (for example, `.gitea/workflows/build.yml`) or other non-interactive tooling maintained in the repository. This keeps build behavior consistent across environments and reduces manual intervention. Possible automations: @@ -141,7 +141,7 @@ After release: A continuous integration and delivery pipeline is implemented using Gitea Actions. The workflows below operationalize the build, validation, and release actions referenced throughout this guide. -### 8.1 Build and Validate Workflow (`.mokogitea/workflows/build.yml`) +### 8.1 Build and Validate Workflow (`.gitea/workflows/build.yml`) ```yaml name: Build and Validate MokoWaaS @@ -188,7 +188,7 @@ jobs: path: mokowaas_ci_build.zip ``` -### 8.2 Release Workflow (`.mokogitea/workflows/release.yml`) +### 8.2 Release Workflow (`.gitea/workflows/release.yml`) ```yaml name: Release MokoWaaS diff --git a/README.md b/README.md index 4725fe8..45555bc 100644 --- a/README.md +++ b/README.md @@ -1,72 +1,24 @@ -# Moko Consulting -- Wiki Archive +# Moko Consulting — Wiki Archive -Consolidated backup of all project wikis. +Consolidated backup of all project wikis from [Gitea](https://git.mokoconsulting.tech). > **Source of truth:** Gitea wikis. This repo is a read-only mirror. ## Projects - -### ClarksvilleFurs - -- [**client-waas-clarksvillefurs**](ClarksvilleFurs/client-waas-clarksvillefurs/) -- 17 pages - -### MokoConsulting - -- [**MokoCRM**](MokoConsulting/MokoCRM/) -- 8 pages -- [**MokoDPCalendarAPI**](MokoConsulting/MokoDPCalendarAPI/) -- 4 pages -- [**MokoDoliAdInsights**](MokoConsulting/MokoDoliAdInsights/) -- 10 pages -- [**MokoDoliArt**](MokoConsulting/MokoDoliArt/) -- 7 pages -- [**MokoDoliAuth**](MokoConsulting/MokoDoliAuth/) -- 2 pages -- [**MokoDoliCare**](MokoConsulting/MokoDoliCare/) -- 14 pages -- [**MokoDoliChimp**](MokoConsulting/MokoDoliChimp/) -- 2 pages -- [**MokoDoliClaude**](MokoConsulting/MokoDoliClaude/) -- 7 pages -- [**MokoDoliCredits**](MokoConsulting/MokoDoliCredits/) -- 7 pages -- [**MokoDoliDymo**](MokoConsulting/MokoDoliDymo/) -- 7 pages -- [**MokoDoliG**](MokoConsulting/MokoDoliG/) -- 4 pages -- [**MokoDoliGithub**](MokoConsulting/MokoDoliGithub/) -- 7 pages -- [**MokoDoliHRM**](MokoConsulting/MokoDoliHRM/) -- 7 pages -- [**MokoDoliMods**](MokoConsulting/MokoDoliMods/) -- 3 pages -- [**MokoDoliMulti**](MokoConsulting/MokoDoliMulti/) -- 8 pages -- [**MokoDoliOffline**](MokoConsulting/MokoDoliOffline/) -- 5 pages -- [**MokoDoliPhoneCom**](MokoConsulting/MokoDoliPhoneCom/) -- 7 pages -- [**MokoDoliProjTemplate**](MokoConsulting/MokoDoliProjTemplate/) -- 7 pages -- [**MokoDoliRelease**](MokoConsulting/MokoDoliRelease/) -- 16 pages -- [**MokoDoliSign**](MokoConsulting/MokoDoliSign/) -- 14 pages -- [**MokoDoliTraining**](MokoConsulting/MokoDoliTraining/) -- 8 pages -- [**MokoDolibarr**](MokoConsulting/MokoDolibarr/) -- 4 pages -- [**MokoGalleryCalendar**](MokoConsulting/MokoGalleryCalendar/) -- 7 pages -- [**MokoGitea**](MokoConsulting/MokoGitea/) -- 5 pages -- [**MokoISOUpdatePortable**](MokoConsulting/MokoISOUpdatePortable/) -- 15 pages -- [**MokoJoomHero**](MokoConsulting/MokoJoomHero/) -- 5 pages -- [**MokoJoomTOS**](MokoConsulting/MokoJoomTOS/) -- 5 pages -- [**MokoJoomla**](MokoConsulting/MokoJoomla/) -- 1 pages -- [**MokoOnyx**](MokoConsulting/MokoOnyx/) -- 10 pages -- [**MokoPerfectPublisher-Discord**](MokoConsulting/MokoPerfectPublisher-Discord/) -- 4 pages -- [**MokoTesting**](MokoConsulting/MokoTesting/) -- 2 pages -- [**MokoWaaS**](MokoConsulting/MokoWaaS/) -- 12 pages -- [**MokoWaaSAnnounce**](MokoConsulting/MokoWaaSAnnounce/) -- 6 pages -- [**MokoWinSetup**](MokoConsulting/MokoWinSetup/) -- 6 pages -- [**Template-Client-WaaS**](MokoConsulting/Template-Client-WaaS/) -- 5 pages -- [**Template-Dolibarr**](MokoConsulting/Template-Dolibarr/) -- 7 pages -- [**Template-Generic**](MokoConsulting/Template-Generic/) -- 4 pages -- [**Template-MCP**](MokoConsulting/Template-MCP/) -- 4 pages -- [**backup-mcp**](MokoConsulting/backup-mcp/) -- 7 pages -- [**deploy-mcp**](MokoConsulting/deploy-mcp/) -- 7 pages -- [**dolibarr-api-mcp**](MokoConsulting/dolibarr-api-mcp/) -- 3 pages -- [**dreamhost-mcp**](MokoConsulting/dreamhost-mcp/) -- 4 pages -- [**gitea-api-mcp**](MokoConsulting/gitea-api-mcp/) -- 3 pages -- [**gitea-org-config**](MokoConsulting/gitea-org-config/) -- 2 pages -- [**gitea-private**](MokoConsulting/gitea-private/) -- 2 pages -- [**gitea-server-setup**](MokoConsulting/gitea-server-setup/) -- 6 pages -- [**issues-mcp**](MokoConsulting/issues-mcp/) -- 1 pages -- [**joomla-api-mcp**](MokoConsulting/joomla-api-mcp/) -- 6 pages -- [**moko-platform**](MokoConsulting/moko-platform/) -- 53 pages -- [**monitor-mcp**](MokoConsulting/monitor-mcp/) -- 7 pages -- [**org-profile**](MokoConsulting/org-profile/) -- 2 pages -- [**project-mcp**](MokoConsulting/project-mcp/) -- 5 pages -- [**ssh-mcp**](MokoConsulting/ssh-mcp/) -- 10 pages -- [**wiki-mcp**](MokoConsulting/wiki-mcp/) -- 4 pages +- [**ClarksvilleFurs**](ClarksvilleFurs/) — 17 pages +- [**MokoConsulting**](MokoConsulting/) — 379 pages +- [**MokoOnyx**](MokoOnyx/) — 10 pages +- [**MokoWaaS**](MokoWaaS/) — 12 pages +- [**Template-Client-WaaS**](Template-Client-WaaS/) — 5 pages +- [**backup-mcp**](backup-mcp/) — 6 pages +- [**client-clarksvillefurs**](client-clarksvillefurs/) — 16 pages +- [**client-waas-clarksvillefurs**](client-waas-clarksvillefurs/) — 16 pages +- [**deploy-mcp**](deploy-mcp/) — 6 pages +- [**joomla-api-mcp**](joomla-api-mcp/) — 6 pages +- [**moko-platform**](moko-platform/) — 54 pages +- [**monitor-mcp**](monitor-mcp/) — 6 pages +- [**ssh-mcp**](ssh-mcp/) — 10 pages --- -*Last synced: 2026-05-11 17:54 UTC* +*Last synced: 2026-05-12 05:01 UTC* diff --git a/moko-platform/ARCHITECTURE.md b/moko-platform/ARCHITECTURE.md index 73f6b1d..a2d18b6 100644 --- a/moko-platform/ARCHITECTURE.md +++ b/moko-platform/ARCHITECTURE.md @@ -161,7 +161,7 @@ All validation modules follow the pattern: --- -## Workflows (`.mokogitea/workflows/`) +## Workflows (`.gitea/workflows/`) | Category | Purpose | |----------|---------| @@ -286,8 +286,16 @@ pip install -r requirements-dev.txt # Development - [Documentation-Standards](Documentation-Standards.-) -- Documentation conventions - [DRY_RUN_PATTERN](DRY_RUN_PATTERN) -- Standard dry-run pattern - [MINIFICATION](MINIFICATION) -- Asset minification pipeline - --- -**Maintained by**: Moko Consulting -**Repository**: https://git.mokoconsulting.tech/MokoConsulting/moko-platform +*Repo: [moko-platform](https://git.mokoconsulting.tech/MokoConsulting/moko-platform) · [moko-platform wiki](https://git.mokoconsulting.tech/MokoConsulting/moko-platform/wiki/Home)* + +| Field | Value | +|---|---| +| Minimum Version | 04.07.00 | +| Platform | all | +| Applies To | All repositories | + +| Revision | Date | Author | Description | +|---|---|---|---| +| 1.0 | 2026-05-09 | Moko Consulting | Initial version | diff --git a/moko-platform/AUTO_CREATE_ORG_PROJECTS.md b/moko-platform/AUTO_CREATE_ORG_PROJECTS.md index 16312d4..ab1e74c 100644 --- a/moko-platform/AUTO_CREATE_ORG_PROJECTS.md +++ b/moko-platform/AUTO_CREATE_ORG_PROJECTS.md @@ -190,3 +190,16 @@ jobs: - [QUICKSTART_ORG_PROJECTS](QUICKSTART_ORG_PROJECTS) -- Quick start guide - [ARCHITECTURE](ARCHITECTURE) -- Platform scripts architecture - [DRY_RUN_PATTERN](DRY_RUN_PATTERN) -- Standard dry-run pattern +--- + +*Repo: [moko-platform](https://git.mokoconsulting.tech/MokoConsulting/moko-platform) · [moko-platform wiki](https://git.mokoconsulting.tech/MokoConsulting/moko-platform/wiki/Home)* + +| Field | Value | +|---|---| +| Minimum Version | 04.07.00 | +| Platform | all | +| Applies To | All repositories | + +| Revision | Date | Author | Description | +|---|---|---|---| +| 1.0 | 2026-05-09 | Moko Consulting | Initial version | diff --git a/moko-platform/DRY_RUN_PATTERN.md b/moko-platform/DRY_RUN_PATTERN.md index 907041e..a5c8f1d 100644 --- a/moko-platform/DRY_RUN_PATTERN.md +++ b/moko-platform/DRY_RUN_PATTERN.md @@ -113,3 +113,16 @@ def main(): - [ARCHITECTURE](ARCHITECTURE) -- Platform scripts architecture - [WORKFLOW_STANDARDS](WORKFLOW_STANDARDS) -- CI/CD workflow conventions +--- + +*Repo: [moko-platform](https://git.mokoconsulting.tech/MokoConsulting/moko-platform) · [moko-platform wiki](https://git.mokoconsulting.tech/MokoConsulting/moko-platform/wiki/Home)* + +| Field | Value | +|---|---| +| Minimum Version | 04.07.00 | +| Platform | all | +| Applies To | All repositories | + +| Revision | Date | Author | Description | +|---|---|---|---| +| 1.0 | 2026-05-09 | Moko Consulting | Initial version | diff --git a/moko-platform/Documentation-Standards.-.-.md b/moko-platform/Documentation-Standards.-.-.md index 3f1069e..3fccd76 100644 --- a/moko-platform/Documentation-Standards.-.-.md +++ b/moko-platform/Documentation-Standards.-.-.md @@ -53,8 +53,8 @@ Every repo must have: | `profile.ps1` | Auto-generated PowerShell profile | | `.mcp.json` | Auto-generated MCP config | | `.gitignore` | Git ignore rules | -| `.mokogitea/.moko-platform` | Repo manifest | -| `.mokogitea/workflows/` | CI/CD workflows | +| `.gitea/.moko-platform` | Repo manifest | +| `.gitea/workflows/` | CI/CD workflows | ## Disallowed @@ -128,3 +128,16 @@ php validate/check_repo_health.php --path /a/MokoCRM --repo MokoConsulting/MokoC - [ARCHITECTURE](ARCHITECTURE) -- Platform scripts architecture - [WORKFLOW_STANDARDS](WORKFLOW_STANDARDS) -- CI/CD workflow conventions - [client-repos](client-repos.-.-) -- Client repository standards +--- + +*Repo: [moko-platform](https://git.mokoconsulting.tech/MokoConsulting/moko-platform) · [moko-platform wiki](https://git.mokoconsulting.tech/MokoConsulting/moko-platform/wiki/Home)* + +| Field | Value | +|---|---| +| Minimum Version | 04.07.00 | +| Platform | all | +| Applies To | All repositories | + +| Revision | Date | Author | Description | +|---|---|---|---| +| 1.0 | 2026-05-09 | Moko Consulting | Initial version | diff --git a/moko-platform/Documentation-Standards.-.md b/moko-platform/Documentation-Standards.-.md index 5929479..dff473f 100644 --- a/moko-platform/Documentation-Standards.-.md +++ b/moko-platform/Documentation-Standards.-.md @@ -100,3 +100,16 @@ php validate/check_repo_health.php --path /a/MokoCRM --repo MokoConsulting/MokoC - [ARCHITECTURE](ARCHITECTURE) -- Platform scripts architecture - [WORKFLOW_STANDARDS](WORKFLOW_STANDARDS) -- CI/CD workflow conventions +--- + +*Repo: [moko-platform](https://git.mokoconsulting.tech/MokoConsulting/moko-platform) · [moko-platform wiki](https://git.mokoconsulting.tech/MokoConsulting/moko-platform/wiki/Home)* + +| Field | Value | +|---|---| +| Minimum Version | 04.07.00 | +| Platform | all | +| Applies To | All repositories | + +| Revision | Date | Author | Description | +|---|---|---|---| +| 1.0 | 2026-05-09 | Moko Consulting | Initial version | diff --git a/moko-platform/File-Header-Standards.-.md b/moko-platform/File-Header-Standards.-.md new file mode 100644 index 0000000..39ad158 --- /dev/null +++ b/moko-platform/File-Header-Standards.-.md @@ -0,0 +1,139 @@ +[← Back to Home](Home) + +# File Header Standards + +> Defines the required and optional elements for source file comment headers across all MokoStandards-governed repositories. + +--- + +## Required: Copyright + SPDX + +Every source file (PHP, JS, CSS, Shell, YAML) **must** contain a copyright notice and SPDX license identifier within the first 20 lines. + +### PHP + +```php +/* Copyright (C) 2026 Moko Consulting + * + * This file is part of a Moko Consulting project. + * + * SPDX-License-Identifier: GPL-3.0-or-later + */ +``` + +### CSS / JavaScript + +```css +@charset "UTF-8"; +/* Copyright (C) 2026 Moko Consulting + + This file is part of a Moko Consulting project. + + SPDX-License-Identifier: GPL-3.0-or-later + */ +``` + +### YAML (workflows) + +```yaml +# Copyright (C) 2026 Moko Consulting +# +# SPDX-License-Identifier: GPL-3.0-or-later +``` + +### Markdown / HTML + +```html + +``` + +--- + +## Optional: FILE INFORMATION Block + +The FILE INFORMATION block provides metadata for tooling (bulk sync, validation, documentation generators). It is **optional** but recommended for key files. + +### Fields + +| Field | Required | Description | +|-------|----------|-------------| +| DEFGROUP | No | Logical group (e.g. `Joomla.Template.Site`) | +| INGROUP | No | Parent group (e.g. `MokoOnyx`) | +| REPO | No | Repository URL | +| PATH | No | File path relative to repo root | +| BRIEF | No | One-line description of the file | + +### Example (PHP) + +```php +/* Copyright (C) 2026 Moko Consulting + * + * This file is part of a Moko Consulting project. + * + * SPDX-License-Identifier: GPL-3.0-or-later + * + * FILE INFORMATION + * DEFGROUP: MokoOnyx.Layout + * INGROUP: MokoOnyx + * PATH: /src/html/layouts/joomla/module/card.php + * BRIEF: Card-style module chrome layout + */ +``` + +### Example (YAML) + +```yaml +# Copyright (C) 2026 Moko Consulting +# +# SPDX-License-Identifier: GPL-3.0-or-later +# +# FILE INFORMATION +# DEFGROUP: Gitea.Workflow +# INGROUP: MokoStandards.Joomla +# REPO: https://git.mokoconsulting.tech/MokoConsulting/MokoStandards-API +# PATH: /templates/workflows/joomla/auto-release.yml.template +# BRIEF: Joomla build and release pipeline +``` + +--- + +## Removed Fields + +| Field | Status | Reason | +|-------|--------|--------| +| **VERSION** | **Removed** | Version is tracked in README.md and manifest files (templateDetails.xml, composer.json, etc.), not in individual file headers. Maintaining version numbers in every file header caused drift and unnecessary churn on bulk updates. | + +--- + +## Validation + +The `check_license_headers.php` validator checks for the presence of `SPDX-License-Identifier:` in the first 20 lines of tracked PHP, JS, CSS, and Shell files. This is an **advisory** check (always exits 0). + +```bash +php validate/check_license_headers.php --path /a/MokoOnyx +``` + +--- + +## Related + +- [Documentation-Standards](Documentation-Standards.-) -- repo health and required files +- [WORKFLOW_STANDARDS](WORKFLOW_STANDARDS) -- CI/CD workflow conventions +--- + +*Repo: [moko-platform](https://git.mokoconsulting.tech/MokoConsulting/moko-platform) · [moko-platform wiki](https://git.mokoconsulting.tech/MokoConsulting/moko-platform/wiki/Home)* + +| Field | Value | +|---|---| +| Minimum Version | 04.07.00 | +| Platform | all | +| Applies To | All repositories | + +| Revision | Date | Author | Description | +|---|---|---|---| +| 1.0 | 2026-05-11 | Moko Consulting | Initial version | diff --git a/moko-platform/Home.md b/moko-platform/Home.md index 3864223..f693f55 100644 --- a/moko-platform/Home.md +++ b/moko-platform/Home.md @@ -48,6 +48,7 @@ vendor/bin/moko inventory -- --path . ## Standards & Governance - [Documentation Standards](Documentation-Standards) -- wiki-first policy, branching, naming, labels +- [File Header Standards](File-Header-Standards) -- copyright, SPDX, FILE INFORMATION block format - [Workflow Standards](WORKFLOW_STANDARDS) -- CI/CD requirements, template sync - [Dry Run Pattern](DRY_RUN_PATTERN) -- safe testing pattern for destructive operations diff --git a/moko-platform/JOOMLA_SYNC.md b/moko-platform/JOOMLA_SYNC.md index 9c5b192..f987381 100644 --- a/moko-platform/JOOMLA_SYNC.md +++ b/moko-platform/JOOMLA_SYNC.md @@ -164,3 +164,16 @@ https://example.com/index.php?option=com_akeebabackup&view=Api&format=raw&method - [SITE_MONITORING](SITE_MONITORING) -- Monitoring architecture and metrics - [WORKFLOW_STANDARDS](WORKFLOW_STANDARDS) -- CI/CD workflow conventions - [client-repos](client-repos.-.-) -- Client repository standards +--- + +*Repo: [moko-platform](https://git.mokoconsulting.tech/MokoConsulting/moko-platform) · [moko-platform wiki](https://git.mokoconsulting.tech/MokoConsulting/moko-platform/wiki/Home)* + +| Field | Value | +|---|---| +| Minimum Version | 04.07.00 | +| Platform | joomla | +| Applies To | Joomla repositories | + +| Revision | Date | Author | Description | +|---|---|---|---| +| 1.0 | 2026-05-09 | Moko Consulting | Initial version | diff --git a/moko-platform/LEGAL_DOC_GENERATOR_WEB_README.md b/moko-platform/LEGAL_DOC_GENERATOR_WEB_README.md index 42833b3..039e5f2 100644 --- a/moko-platform/LEGAL_DOC_GENERATOR_WEB_README.md +++ b/moko-platform/LEGAL_DOC_GENERATOR_WEB_README.md @@ -109,3 +109,16 @@ php scripts/legal_doc_generator.php --type membership --company-name "Acme Inc" - [ARCHITECTURE](ARCHITECTURE) -- Platform scripts architecture - [NEW_SCRIPTS](NEW_SCRIPTS) -- New automation scripts overview +--- + +*Repo: [moko-platform](https://git.mokoconsulting.tech/MokoConsulting/moko-platform) · [moko-platform wiki](https://git.mokoconsulting.tech/MokoConsulting/moko-platform/wiki/Home)* + +| Field | Value | +|---|---| +| Minimum Version | 04.07.00 | +| Platform | all | +| Applies To | moko-platform | + +| Revision | Date | Author | Description | +|---|---|---|---| +| 1.0 | 2026-05-09 | Moko Consulting | Initial version | diff --git a/moko-platform/MCP-Servers.-.-.-.md b/moko-platform/MCP-Servers.-.-.-.md index 9383718..7ed315d 100644 --- a/moko-platform/MCP-Servers.-.-.-.md +++ b/moko-platform/MCP-Servers.-.-.-.md @@ -53,3 +53,16 @@ Moko Consulting maintains 10 MCP servers for Claude Code integration. - [ARCHITECTURE](ARCHITECTURE) -- Platform scripts architecture - [WORKFLOW_STANDARDS](WORKFLOW_STANDARDS) -- CI/CD workflow conventions - [client-repos](client-repos.-.-) -- Client repository standards +--- + +*Repo: [moko-platform](https://git.mokoconsulting.tech/MokoConsulting/moko-platform) · [moko-platform wiki](https://git.mokoconsulting.tech/MokoConsulting/moko-platform/wiki/Home)* + +| Field | Value | +|---|---| +| Minimum Version | 04.07.00 | +| Platform | mcp-server | +| Applies To | MCP server repositories | + +| Revision | Date | Author | Description | +|---|---|---|---| +| 1.0 | 2026-05-09 | Moko Consulting | Initial version | diff --git a/moko-platform/MINIFICATION.md b/moko-platform/MINIFICATION.md index 3047f11..fdf6789 100644 --- a/moko-platform/MINIFICATION.md +++ b/moko-platform/MINIFICATION.md @@ -126,10 +126,15 @@ Vendor libraries (e.g. Font Awesome) ship pre-minified only. Unminified vendor s - [WIKI_STANDARDS](WIKI_STANDARDS) -- repo file requirements - [WORKFLOW_STANDARDS](WORKFLOW_STANDARDS) -- CI/CD conventions - --- -*Repo: [moko-platform](https://git.mokoconsulting.tech/MokoConsulting/moko-platform) · [MokoStandards](https://git.mokoconsulting.tech/MokoConsulting/moko-platform/wiki/Home)* +*Repo: [moko-platform](https://git.mokoconsulting.tech/MokoConsulting/moko-platform) · [moko-platform wiki](https://git.mokoconsulting.tech/MokoConsulting/moko-platform/wiki/Home)* + +| Field | Value | +|---|---| +| Minimum Version | 04.07.00 | +| Platform | joomla | +| Applies To | Joomla repositories | | Revision | Date | Author | Description | |---|---|---|---| diff --git a/moko-platform/NEW_SCRIPTS.md b/moko-platform/NEW_SCRIPTS.md index ba95e49..b701d39 100644 --- a/moko-platform/NEW_SCRIPTS.md +++ b/moko-platform/NEW_SCRIPTS.md @@ -14,7 +14,6 @@ The following scripts have been added to enhance automation capabilities across ### `analyze_dependencies.py` -**Location:** `scripts/analysis/analyze_dependencies.py` Analyzes project dependencies across multiple package managers (Python, npm, composer). @@ -26,7 +25,6 @@ python3 scripts/analysis/analyze_dependencies.py --check-outdated ### `code_metrics.py` -**Location:** `scripts/analysis/code_metrics.py` Analyzes code metrics including lines of code, file counts, and language distribution. @@ -41,7 +39,6 @@ python3 scripts/analysis/code_metrics.py /path/to/project --json ### `setup_dev_environment.py` -**Location:** `scripts/automation/setup_dev_environment.py` Quick setup script for new contributors to configure their development environment. @@ -52,7 +49,6 @@ python3 scripts/automation/setup_dev_environment.py --skip-install ### `check_outdated_actions.py` -**Location:** `scripts/automation/check_outdated_actions.py` Checks for outdated Gitea Actions in workflow files. @@ -67,7 +63,6 @@ python3 scripts/automation/check_outdated_actions.py --workflow-dir path/to/work ### `check_markdown_links.py` -**Location:** `scripts/validate/check_markdown_links.py` Validates links in markdown files to ensure they are not broken. Returns exit code 1 if broken links are found. @@ -78,7 +73,6 @@ python3 scripts/validate/check_markdown_links.py docs/ --skip-external ### `find_todos.py` -**Location:** `scripts/validate/find_todos.py` Finds and reports TODO, FIXME, and other code comments across the codebase. @@ -89,7 +83,6 @@ python3 scripts/validate/find_todos.py --markers TODO FIXME --group-by file ### `check_license_headers.py` -**Location:** `scripts/validate/check_license_headers.py` Checks and optionally fixes missing or incorrect GPL-3.0-or-later license headers. Returns exit code 1 if missing headers are found. @@ -104,7 +97,6 @@ python3 scripts/validate/check_license_headers.py --fix --year 2026 ### `update_copyright_year.py` -**Location:** `scripts/maintenance/update_copyright_year.py` Updates copyright year in file headers across the codebase. Dry-run by default. @@ -115,7 +107,6 @@ python3 scripts/maintenance/update_copyright_year.py --year 2026 --apply ### `clean_old_branches.py` -**Location:** `scripts/maintenance/clean_old_branches.py` Identifies and optionally deletes old Git branches. Protects main/master/develop. @@ -131,7 +122,6 @@ python3 scripts/maintenance/clean_old_branches.py --delete-all --force ### `generate_script_catalog.py` -**Location:** `scripts/docs/generate_script_catalog.py` Generates a comprehensive catalog of all scripts in the repository. @@ -142,7 +132,6 @@ python3 scripts/docs/generate_script_catalog.py --output SCRIPT_CATALOG.md ### `check_doc_coverage.py` -**Location:** `scripts/docs/check_doc_coverage.py` Checks documentation coverage by identifying undocumented scripts and templates. @@ -156,7 +145,6 @@ python3 scripts/docs/check_doc_coverage.py ### `git_helper.sh` -**Location:** `scripts/run/git_helper.sh` Helper script for common git operations with enhanced output. @@ -191,3 +179,16 @@ All new scripts include: comprehensive docstrings, CLI argument parsing, `--help - [ARCHITECTURE](ARCHITECTURE) -- Platform scripts architecture - [DRY_RUN_PATTERN](DRY_RUN_PATTERN) -- Standard dry-run pattern - [WORKFLOW_STANDARDS](WORKFLOW_STANDARDS) -- CI/CD workflow conventions +--- + +*Repo: [moko-platform](https://git.mokoconsulting.tech/MokoConsulting/moko-platform) · [moko-platform wiki](https://git.mokoconsulting.tech/MokoConsulting/moko-platform/wiki/Home)* + +| Field | Value | +|---|---| +| Minimum Version | 04.07.00 | +| Platform | all | +| Applies To | moko-platform | + +| Revision | Date | Author | Description | +|---|---|---|---| +| 1.0 | 2026-05-09 | Moko Consulting | Initial version | diff --git a/moko-platform/QUICKSTART_ORG_PROJECTS.md b/moko-platform/QUICKSTART_ORG_PROJECTS.md index 06adfa3..1bd5d91 100644 --- a/moko-platform/QUICKSTART_ORG_PROJECTS.md +++ b/moko-platform/QUICKSTART_ORG_PROJECTS.md @@ -114,3 +114,16 @@ python3 scripts/create_repo_project.py REPO_NAME --type generic - [AUTO_CREATE_ORG_PROJECTS](AUTO_CREATE_ORG_PROJECTS) -- Full documentation - [ARCHITECTURE](ARCHITECTURE) -- Platform scripts architecture +--- + +*Repo: [moko-platform](https://git.mokoconsulting.tech/MokoConsulting/moko-platform) · [moko-platform wiki](https://git.mokoconsulting.tech/MokoConsulting/moko-platform/wiki/Home)* + +| Field | Value | +|---|---| +| Minimum Version | 04.07.00 | +| Platform | all | +| Applies To | All repositories | + +| Revision | Date | Author | Description | +|---|---|---|---| +| 1.0 | 2026-05-09 | Moko Consulting | Initial version | diff --git a/moko-platform/SITE_MONITORING.md b/moko-platform/SITE_MONITORING.md index be0383c..07ce19d 100644 --- a/moko-platform/SITE_MONITORING.md +++ b/moko-platform/SITE_MONITORING.md @@ -196,3 +196,16 @@ Template at `monitoring/grafana/client-joomla-dashboard.json` in the client temp - [ARCHITECTURE](ARCHITECTURE) -- Platform scripts architecture - [JOOMLA_SYNC](JOOMLA_SYNC) -- Joomla extension sync between servers - [MCP-Servers](MCP-Servers.-.-) -- MCP server fleet overview +--- + +*Repo: [moko-platform](https://git.mokoconsulting.tech/MokoConsulting/moko-platform) · [moko-platform wiki](https://git.mokoconsulting.tech/MokoConsulting/moko-platform/wiki/Home)* + +| Field | Value | +|---|---| +| Minimum Version | 04.07.00 | +| Platform | joomla | +| Applies To | Joomla and Dolibarr client sites | + +| Revision | Date | Author | Description | +|---|---|---|---| +| 1.0 | 2026-05-09 | Moko Consulting | Initial version | diff --git a/moko-platform/WIKI_STANDARDS.md b/moko-platform/WIKI_STANDARDS.md index 91c57ac..b3f8304 100644 --- a/moko-platform/WIKI_STANDARDS.md +++ b/moko-platform/WIKI_STANDARDS.md @@ -30,7 +30,13 @@ Content... --- -*Repo: [RepoName](repo-url) · [MokoStandards](https://git.mokoconsulting.tech/MokoConsulting/moko-platform/wiki/Home)* +*Repo: [RepoName](repo-url) · [moko-platform](https://git.mokoconsulting.tech/MokoConsulting/moko-platform/wiki/Home)* + +| Field | Value | +|---|---| +| Minimum Version | XX.YY.ZZ | +| Platform | joomla / dolibarr / mcp-server / generic | +| Applies To | All repositories / Joomla only / etc. | | Revision | Date | Author | Description | |---|---|---|---| @@ -46,7 +52,7 @@ Content... | Description | After title | 1-2 sentence summary | | Horizontal rules | Between major sections | `---` separators | | Related section | Before footer | Links to related pages | -| Metadata footer | Last lines | Repo link, MokoStandards link, revision table | +| Metadata footer | Last lines | Repo link, MokoStandards link, metadata table, revision table | --- @@ -114,18 +120,32 @@ Every repo wiki must have a Home page with: ## Metadata Footer -Every page ends with: +Every page ends with a metadata section containing the repo link, a metadata table, and a revision history table. ```markdown --- *Repo: [RepoName](https://git.mokoconsulting.tech/Owner/Repo) · [MokoStandards](https://git.mokoconsulting.tech/MokoConsulting/moko-platform/wiki/Home)* +| Field | Value | +|---|---| +| Minimum Version | 04.07.00 | + | Revision | Date | Author | Description | |---|---|---|---| | 1.0 | 2026-05-09 | Moko Consulting | Initial version | ``` +### Metadata table fields + +| Field | Required | Description | +|---|---|---| +| **Minimum Version** | Yes | The MokoStandards version this page applies to. Use the standards version from the `.mokostandards` manifest, not the repo's own version. Update when content depends on features from a newer standards version. Omit only on the Home page (which is version-agnostic). | +| **Platform** | Recommended | Which platform(s) the page applies to: `joomla`, `dolibarr`, `mcp-server`, `generic`, or `all` | +| **Applies To** | Recommended | Scope: `All repositories`, `Joomla extensions only`, `MCP servers only`, specific repo name, etc. | + +Additional fields may be added per-page as needed. + --- ## Required Repository Files @@ -229,15 +249,21 @@ All wikis are backed up daily to [mokoconsulting-tech/wiki](https://github.com/m ## Related +- [File-Header-Standards](File-Header-Standards) -- source file comment headers - [MINIFICATION](MINIFICATION) -- asset build standards - [WORKFLOW_STANDARDS](WORKFLOW_STANDARDS) -- CI/CD conventions - [Documentation-Standards](Documentation-Standards) -- code documentation standards --- -*Repo: [moko-platform](https://git.mokoconsulting.tech/MokoConsulting/moko-platform) · [MokoStandards](https://git.mokoconsulting.tech/MokoConsulting/moko-platform/wiki/Home)* +*Repo: [moko-platform](https://git.mokoconsulting.tech/MokoConsulting/moko-platform) · [moko-platform wiki](https://git.mokoconsulting.tech/MokoConsulting/moko-platform/wiki/Home)* + +| Field | Value | +|---|---| +| Minimum Version | 04.07.00 | | Revision | Date | Author | Description | |---|---|---|---| -| 1.0 | 2026-05-09 | Moko Consulting | Initial wiki standards | +| 1.0 | 2026-05-09 | Moko Consulting | Initial version | | 2.0 | 2026-05-10 | Moko Consulting | Added CLAUDE.md standard, repo health check details, required/disallowed files | +| 3.0 | 2026-05-11 | Moko Consulting | Added Minimum Version field to metadata table; linked File-Header-Standards | diff --git a/moko-platform/WORKFLOW_STANDARDS.md b/moko-platform/WORKFLOW_STANDARDS.md index 4251a3f..fb6dc8e 100644 --- a/moko-platform/WORKFLOW_STANDARDS.md +++ b/moko-platform/WORKFLOW_STANDARDS.md @@ -25,7 +25,7 @@ moko-platform-Template-Client → client-clarksvillefurs, client-ki bulk-repo-sync.yml (API repo) → RepositorySynchronizer.php detects platform type → Clones the matching template repo to /tmp/ - → Copies .mokogitea/workflows/*.yml from template → target repo + → Copies .gitea/workflows/*.yml from template → target repo ``` No workflow files are stored in the API repo. This prevents drift. @@ -153,25 +153,25 @@ To update workflows across all repos from the canonical template: # Joomla repos -- sync from unified template for REPO in MokoOnyx MokoCassiopeia MokoJGDPC MokoJoomHero MokoJoomTOS MokoWaaS MokoWaaSAnnounce MokoDPCalendarAPI; do cd /a/$REPO - rm -f .mokogitea/workflows/*.yml - cp /a/moko-platform-Template-Joomla/.mokogitea/workflows/*.yml .mokogitea/workflows/ - git add .mokogitea/workflows/ && git commit -m "chore: sync workflows" && git push + rm -f .gitea/workflows/*.yml + cp /a/moko-platform-Template-Joomla/.gitea/workflows/*.yml .gitea/workflows/ + git add .gitea/workflows/ && git commit -m "chore: sync workflows" && git push done # Dolibarr repos -- sync from Dolibarr template for REPO in MokoCRM MokoDoliForm MokoDoliAuth MokoDolibarr ...; do cd /a/$REPO - rm -f .mokogitea/workflows/*.yml - cp /a/moko-platform-Template-Dolibarr/.mokogitea/workflows/*.yml .mokogitea/workflows/ - git add .mokogitea/workflows/ && git commit -m "chore: sync workflows" && git push + rm -f .gitea/workflows/*.yml + cp /a/moko-platform-Template-Dolibarr/.gitea/workflows/*.yml .gitea/workflows/ + git add .gitea/workflows/ && git commit -m "chore: sync workflows" && git push done # Client repos -- sync from Client template for REPO in client-clarksvillefurs client-kiddieland; do cd /a/$REPO - rm -f .mokogitea/workflows/*.yml - cp /a/moko-platform-Template-Client/.mokogitea/workflows/*.yml .mokogitea/workflows/ - git add .mokogitea/workflows/ && git commit -m "chore: sync workflows" && git push + rm -f .gitea/workflows/*.yml + cp /a/moko-platform-Template-Client/.gitea/workflows/*.yml .gitea/workflows/ + git add .gitea/workflows/ && git commit -m "chore: sync workflows" && git push done ``` @@ -206,3 +206,16 @@ done - [MINIFICATION](MINIFICATION) -- Asset minification pipeline - [client-repos](client-repos.-.-) -- Client repository standards - [Documentation-Standards](Documentation-Standards.-) -- Documentation conventions +--- + +*Repo: [moko-platform](https://git.mokoconsulting.tech/MokoConsulting/moko-platform) · [moko-platform wiki](https://git.mokoconsulting.tech/MokoConsulting/moko-platform/wiki/Home)* + +| Field | Value | +|---|---| +| Minimum Version | 04.07.00 | +| Platform | all | +| Applies To | All repositories | + +| Revision | Date | Author | Description | +|---|---|---|---| +| 1.0 | 2026-05-09 | Moko Consulting | Initial version | diff --git a/moko-platform/api-automation-index.-.-.md b/moko-platform/api-automation-index.-.-.md index edd0d99..1305929 100644 --- a/moko-platform/api-automation-index.-.-.md +++ b/moko-platform/api-automation-index.-.-.md @@ -115,10 +115,17 @@ php api/automation/repo_cleanup.php --check-drift --json | `--all` | Run all cleanup operations | | `--yes` | Auto-confirm prompts | | `--dry-run` | Preview changes without making them | -| `--json` | Output results as JSON | - ---- - -**Location:** `api/automation/` -**Mirrors:** `api/automation/` -**Last Updated:** 2026-04-04 +| `--json` | Output results as JSON | +--- + +*Repo: [moko-platform](https://git.mokoconsulting.tech/MokoConsulting/moko-platform) · [moko-platform wiki](https://git.mokoconsulting.tech/MokoConsulting/moko-platform/wiki/Home)* + +| Field | Value | +|---|---| +| Minimum Version | 04.07.00 | +| Platform | all | +| Applies To | moko-platform | + +| Revision | Date | Author | Description | +|---|---|---|---| +| 1.0 | 2026-05-08 | Moko Consulting | Initial version | diff --git a/moko-platform/api-definitions-default-index.-.-.md b/moko-platform/api-definitions-default-index.-.-.md index ad4853c..fd3fb20 100644 --- a/moko-platform/api-definitions-default-index.-.-.md +++ b/moko-platform/api-definitions-default-index.-.-.md @@ -205,6 +205,17 @@ Definitions support multiple requirement levels: - [Synced Definitions](sync-index) - Auto-generated repository definitions - [Schema Guide](..-..-docs-schemas-repohealth-schema-guide) - Complete schema specification - [Validation Guide](..-..-docs-guide-validation-auto-detection) - Platform detection and validation -- [Main Definitions README](README) - Overview of definitions structure - +- [Main Definitions README](README) - Overview of definitions structure --- + +*Repo: [moko-platform](https://git.mokoconsulting.tech/MokoConsulting/moko-platform) · [moko-platform wiki](https://git.mokoconsulting.tech/MokoConsulting/moko-platform/wiki/Home)* + +| Field | Value | +|---|---| +| Minimum Version | 04.07.00 | +| Platform | all | +| Applies To | moko-platform | + +| Revision | Date | Author | Description | +|---|---|---|---| +| 1.0 | 2026-05-08 | Moko Consulting | Initial version | diff --git a/moko-platform/api-definitions-sync-index.-.-.md b/moko-platform/api-definitions-sync-index.-.-.md index 35ac31e..8e7d284 100644 --- a/moko-platform/api-definitions-sync-index.-.-.md +++ b/moko-platform/api-definitions-sync-index.-.-.md @@ -215,6 +215,17 @@ For repositories that already have `.github/override.tf` files: - [Default Definitions](default-README) - Base platform definitions - [Schema Guide](..-..-docs-schemas-repohealth-schema-guide) - Definition schema specification - [Bulk Sync Documentation](..-..-docs-automation-bulk-repo-sync) - Bulk sync process -- [Validation Guide](..-..-docs-guide-validation-auto-detection) - Platform detection and validation - +- [Validation Guide](..-..-docs-guide-validation-auto-detection) - Platform detection and validation --- + +*Repo: [moko-platform](https://git.mokoconsulting.tech/MokoConsulting/moko-platform) · [moko-platform wiki](https://git.mokoconsulting.tech/MokoConsulting/moko-platform/wiki/Home)* + +| Field | Value | +|---|---| +| Minimum Version | 04.07.00 | +| Platform | all | +| Applies To | moko-platform | + +| Revision | Date | Author | Description | +|---|---|---|---| +| 1.0 | 2026-05-08 | Moko Consulting | Initial version | diff --git a/moko-platform/api-deploy-index.-.-.md b/moko-platform/api-deploy-index.-.-.md index 0eedac8..4b7c630 100644 --- a/moko-platform/api-deploy-index.-.-.md +++ b/moko-platform/api-deploy-index.-.-.md @@ -139,10 +139,17 @@ See [Deploy Workflows](..-workflows-dev-deployment) for workflow usage. ### GitHub Secrets and Variables Reference -When called from CI, the script reads credentials from environment variables set by the workflow. See the [SFTP Deployment Guide](../../deployment/sftp.md#github-secrets-and-variables) for the full secrets/variables tables for `DEV_FTP_*` and `DEMO_FTP_*` environments, including types (Secret vs. Variable) and scopes (Org vs. Repo). - ---- - -**Location:** `api/deploy/` -**Mirrors:** `api/deploy/` -**Last Updated:** 2026-04-07 +When called from CI, the script reads credentials from environment variables set by the workflow. See the [SFTP Deployment Guide](../../deployment/sftp.md#github-secrets-and-variables) for the full secrets/variables tables for `DEV_FTP_*` and `DEMO_FTP_*` environments, including types (Secret vs. Variable) and scopes (Org vs. Repo). +--- + +*Repo: [moko-platform](https://git.mokoconsulting.tech/MokoConsulting/moko-platform) · [moko-platform wiki](https://git.mokoconsulting.tech/MokoConsulting/moko-platform/wiki/Home)* + +| Field | Value | +|---|---| +| Minimum Version | 04.07.00 | +| Platform | all | +| Applies To | All repositories | + +| Revision | Date | Author | Description | +|---|---|---|---| +| 1.0 | 2026-05-08 | Moko Consulting | Initial version | diff --git a/moko-platform/api-fix-index.-.-.md b/moko-platform/api-fix-index.-.-.md index 88fa45a..fdacf9b 100644 --- a/moko-platform/api-fix-index.-.-.md +++ b/moko-platform/api-fix-index.-.-.md @@ -91,10 +91,17 @@ php api/fix/fix_trailing_spaces.php --path . --dry-run | `--path` | `.` | Repository root | | `--type ` | all | Limit fixes to files of this type | | `--dry-run` | off | Show files that would be changed | -| `--help` | — | Show help and exit | - ---- - -**Location:** `api/fix/` -**Mirrors:** `api/fix/` -**Last Updated:** 2026-03-13 +| `--help` | — | Show help and exit | +--- + +*Repo: [moko-platform](https://git.mokoconsulting.tech/MokoConsulting/moko-platform) · [moko-platform wiki](https://git.mokoconsulting.tech/MokoConsulting/moko-platform/wiki/Home)* + +| Field | Value | +|---|---| +| Minimum Version | 04.07.00 | +| Platform | all | +| Applies To | All repositories | + +| Revision | Date | Author | Description | +|---|---|---|---| +| 1.0 | 2026-05-08 | Moko Consulting | Initial version | diff --git a/moko-platform/api-index.-.-.md b/moko-platform/api-index.-.-.md index 281efef..6f7d240 100644 --- a/moko-platform/api-index.-.-.md +++ b/moko-platform/api-index.-.-.md @@ -313,6 +313,17 @@ Repository validation follows this pipeline: - [Validation Guide](../guide/validation/) - Complete validation documentation - [Automation Guide](../automation/) - Automation workflows and processes - [Schema Guide](../schemas/repohealth/) - Repository structure schemas -- [Development Guide](../development/) - Development guidelines and standards - +- [Development Guide](../development/) - Development guidelines and standards --- + +*Repo: [moko-platform](https://git.mokoconsulting.tech/MokoConsulting/moko-platform) · [moko-platform wiki](https://git.mokoconsulting.tech/MokoConsulting/moko-platform/wiki/Home)* + +| Field | Value | +|---|---| +| Minimum Version | 04.07.00 | +| Platform | all | +| Applies To | moko-platform | + +| Revision | Date | Author | Description | +|---|---|---|---| +| 1.0 | 2026-05-08 | Moko Consulting | Initial version | diff --git a/moko-platform/api-maintenance-index.-.-.md b/moko-platform/api-maintenance-index.-.-.md index c934874..f072597 100644 --- a/moko-platform/api-maintenance-index.-.-.md +++ b/moko-platform/api-maintenance-index.-.-.md @@ -157,10 +157,17 @@ php api/maintenance/repo_inventory.php --json |--------|-------------| | `--dry-run` | Preview without posting issue | | `--json` | JSON output to stdout | -| `--org ` | GitHub organization (default: `MokoConsulting`) | - ---- - -**Location:** `api/maintenance/` -**Mirrors:** `api/maintenance/` -**Last Updated:** 2026-03-30 +| `--org ` | GitHub organization (default: `MokoConsulting`) | +--- + +*Repo: [moko-platform](https://git.mokoconsulting.tech/MokoConsulting/moko-platform) · [moko-platform wiki](https://git.mokoconsulting.tech/MokoConsulting/moko-platform/wiki/Home)* + +| Field | Value | +|---|---| +| Minimum Version | 04.07.00 | +| Platform | all | +| Applies To | moko-platform | + +| Revision | Date | Author | Description | +|---|---|---|---| +| 1.0 | 2026-05-08 | Moko Consulting | Initial version | diff --git a/moko-platform/api-plugin-index.-.-.md b/moko-platform/api-plugin-index.-.-.md index 1309460..bb86501 100644 --- a/moko-platform/api-plugin-index.-.-.md +++ b/moko-platform/api-plugin-index.-.-.md @@ -153,10 +153,17 @@ php api/plugin_list.php --type dolibarr --details # Simple list of plugin type names only php api/plugin_list.php --format simple -``` - ---- - -**Location:** `api/plugin/` -**Mirrors:** `api/plugin_*.php` -**Last Updated:** 2026-03-13 +``` +--- + +*Repo: [moko-platform](https://git.mokoconsulting.tech/MokoConsulting/moko-platform) · [moko-platform wiki](https://git.mokoconsulting.tech/MokoConsulting/moko-platform/wiki/Home)* + +| Field | Value | +|---|---| +| Minimum Version | 04.07.00 | +| Platform | joomla | +| Applies To | Joomla repositories | + +| Revision | Date | Author | Description | +|---|---|---|---| +| 1.0 | 2026-05-08 | Moko Consulting | Initial version | diff --git a/moko-platform/api-tests-index.-.-.md b/moko-platform/api-tests-index.-.-.md index 3384c0f..7c22f5c 100644 --- a/moko-platform/api-tests-index.-.-.md +++ b/moko-platform/api-tests-index.-.-.md @@ -54,6 +54,17 @@ See [`api/tests/sample/index.md`](sample-index) for details. ## Related Documentation -- [API Overview](index) - +- [API Overview](index) --- + +*Repo: [moko-platform](https://git.mokoconsulting.tech/MokoConsulting/moko-platform) · [moko-platform wiki](https://git.mokoconsulting.tech/MokoConsulting/moko-platform/wiki/Home)* + +| Field | Value | +|---|---| +| Minimum Version | 04.07.00 | +| Platform | all | +| Applies To | moko-platform | + +| Revision | Date | Author | Description | +|---|---|---|---| +| 1.0 | 2026-05-08 | Moko Consulting | Initial version | diff --git a/moko-platform/api-tests-sample-index.-.-.md b/moko-platform/api-tests-sample-index.-.-.md index 6946706..b42708b 100644 --- a/moko-platform/api-tests-sample-index.-.-.md +++ b/moko-platform/api-tests-sample-index.-.-.md @@ -48,6 +48,17 @@ $score = $checker->run(); // should reach passing threshold - [Tests Documentation](index) - [Validation Scripts](..-validate-index) -- [API Overview](..-index) - +- [API Overview](..-index) --- + +*Repo: [moko-platform](https://git.mokoconsulting.tech/MokoConsulting/moko-platform) · [moko-platform wiki](https://git.mokoconsulting.tech/MokoConsulting/moko-platform/wiki/Home)* + +| Field | Value | +|---|---| +| Minimum Version | 04.07.00 | +| Platform | all | +| Applies To | moko-platform | + +| Revision | Date | Author | Description | +|---|---|---|---| +| 1.0 | 2026-05-08 | Moko Consulting | Initial version | diff --git a/moko-platform/api-validate-index.-.-.md b/moko-platform/api-validate-index.-.-.md index 590651f..58f9099 100644 --- a/moko-platform/api-validate-index.-.-.md +++ b/moko-platform/api-validate-index.-.-.md @@ -253,10 +253,17 @@ php api/validate/check_composer_deps.php --all --json | `--repo ` | Check a single repository | | `--all` | Check all governed repos | | `--json` | Machine-readable JSON output | -| `--org ` | GitHub organization (default: `MokoConsulting`) | - ---- - -**Location:** `api/validate/` -**Mirrors:** `api/validate/` -**Last Updated:** 2026-03-30 +| `--org ` | GitHub organization (default: `MokoConsulting`) | +--- + +*Repo: [moko-platform](https://git.mokoconsulting.tech/MokoConsulting/moko-platform) · [moko-platform wiki](https://git.mokoconsulting.tech/MokoConsulting/moko-platform/wiki/Home)* + +| Field | Value | +|---|---| +| Minimum Version | 04.07.00 | +| Platform | all | +| Applies To | All repositories | + +| Revision | Date | Author | Description | +|---|---|---|---| +| 1.0 | 2026-05-08 | Moko Consulting | Initial version | diff --git a/moko-platform/automation-README.-.-.md b/moko-platform/automation-README.-.-.md index 4420ca8..0bb4478 100644 --- a/moko-platform/automation-README.-.-.md +++ b/moko-platform/automation-README.-.-.md @@ -1,138 +1,151 @@ ← [Home](Home) -[![moko-platform](https://img.shields.io/badge/moko-platform-05.00.00-orange)](https://git.mokoconsulting.tech/MokoConsulting/moko-platform) - -# Automation Documentation - -Documentation for all automation systems deployed across moko-platform organization repositories. - -## Available Documentation - -### Automation Scripts -For details on available automation scripts, see: -- [Automation Scripts](..-api-automation-index) - Bulk repository updates -- [Maintenance Scripts](..-api-maintenance-index) - Repository maintenance utilities -- [Release Scripts](..-api-release-index) - Release automation utilities - -### CLI Tools (`api/cli/`) - -| Script | Purpose | -|--------|---------| -| `create_repo.php` | Scaffold new governed repo (7-step: create, topics, .mokostandards, README, labels, sync, project) | -| `archive_repo.php` | Retire repo (close PRs/issues, archive on GitHub, remove sync def, create record) | -| `create_project.php` | Provision GitHub Projects V2 from 10 platform templates | -| `sync_rulesets.php` | Apply MAIN/VERSION/DEV rulesets to all repos via GitHub API | -| `release.php` | Full release flow (bump, propagate, version branch, tag) | -| `version_bump.php` | Bump version (major/minor/patch) | -| `version_read.php` | Read current version from README | -| `version_set_platform.php` | Set platform-specific version (Dolibarr/Joomla) | -| `platform_detect.php` | Detect platform type from repo | -| `release_notes.php` | Generate release notes from CHANGELOG | - -### Validation (`api/validate/`) - -| Script | Purpose | -|--------|---------| -| `check_repo_health.php` | 118-point health score (9 categories incl. rulesets) | -| `check_composer_deps.php` | Validate enterprise dependency version across all repos | -| `scan_drift.php` | Detect file/config drift from standards | - -### Maintenance (`api/maintenance/`) - -| Script | Purpose | -|--------|---------| -| `rotate_secrets.php` | Audit DEV/DEMO/RS FTP secrets and variables | -| `repo_inventory.php` | Live inventory dashboard posted as GitHub issue | -| `repo_cleanup.php` | 8 cleanup operations (branches, PRs, retired workflows, etc.) | -| `update_version_from_readme.php` | Propagate version across all file headers and badges | -| `setup_labels.php` | Deploy 58-label standard set | - -## CI/CD Pipeline Overview - -The complete automation pipeline runs on every push and pull request. - -```mermaid -flowchart TD - A[Code Push/PR] --> B[Gitea Actions Trigger] - - B --> C[Standards Compliance Check] - B --> D[Security Scanning] - B --> E[Code Quality Analysis] - - C --> C1[File Headers] - C --> C2[Tabs/Spaces Policy] - C --> C3[File Encoding] - C --> C4[Trailing Spaces] - C --> C5[CHANGELOG Format] - - D --> D1[Secret Scanning] - D --> D2[CodeQL Analysis] - D --> D3[Dependency Review] - - E --> E1[PHP Syntax Check] - E --> E2[Shell Script Validation] - E --> E4[Markdown Links] - - C1 --> F{All Checks Pass?} - C2 --> F - C3 --> F - C4 --> F - C5 --> F - D1 --> F - D2 --> F - D3 --> F - E1 --> F - E2 --> F - E4 --> F - - F -->|Yes| G[✓ Build Passes] - F -->|No| H[✗ Build Fails] - - G --> I{Is Main Branch?} - I -->|Yes| J[Trigger Auto-Release] - I -->|No| K[Ready for Merge] - - style A fill:#e1f5ff - style G fill:#c8e6c9 - style H fill:#ffccbc -``` - -> Full diagram set: [docs/visual/cicd-pipeline.md](visual-cicd-pipeline) - -## Bulk Sync Workflow - -`bulk_sync.php` synchronizes standards across all organization repositories with checkpoint recovery. - -```mermaid -flowchart LR - A[bulk_sync.php] --> B{--dry-run?} - B -->|Yes| C[Simulate all operations\nNo API writes\nNo checkpoints written] - B -->|No| D[Execute real sync\nWrite to GitHub API\nCheckpoint after each repo] - - style C fill:#fff9c4 - style D fill:#e1f5ff -``` - -> Full diagram: [docs/visual/bulk-sync-workflow.md](visual-bulk-sync-workflow) - -## Related Documentation - -### Scripts Documentation -- [Maintenance Scripts](..-api-maintenance-index) -- [Release Scripts](..-api-release-index) -- [Automation Scripts](..-api-automation-index) - -### Policy & Strategy -- [Branching Strategy](policy-branching-strategy) -- [Release Management](policy-governance-release-management) - -## Support - -For automation-related issues: -1. Review script documentation in [api/automation/](../../api/automation/) -2. Contact moko-platform maintainers - +[![moko-platform](https://img.shields.io/badge/moko-platform-04.06.00-orange)](https://git.mokoconsulting.tech/MokoConsulting/moko-platform) + +# Automation Documentation + +Documentation for all automation systems deployed across moko-platform organization repositories. + +## Available Documentation + +### Automation Scripts +For details on available automation scripts, see: +- [Automation Scripts](..-api-automation-index) - Bulk repository updates +- [Maintenance Scripts](..-api-maintenance-index) - Repository maintenance utilities +- [Release Scripts](..-api-release-index) - Release automation utilities + +### CLI Tools (`api/cli/`) + +| Script | Purpose | +|--------|---------| +| `create_repo.php` | Scaffold new governed repo (7-step: create, topics, .mokostandards, README, labels, sync, project) | +| `archive_repo.php` | Retire repo (close PRs/issues, archive on GitHub, remove sync def, create record) | +| `create_project.php` | Provision GitHub Projects V2 from 10 platform templates | +| `sync_rulesets.php` | Apply MAIN/VERSION/DEV rulesets to all repos via GitHub API | +| `release.php` | Full release flow (bump, propagate, version branch, tag) | +| `version_bump.php` | Bump version (major/minor/patch) | +| `version_read.php` | Read current version from README | +| `version_set_platform.php` | Set platform-specific version (Dolibarr/Joomla) | +| `platform_detect.php` | Detect platform type from repo | +| `release_notes.php` | Generate release notes from CHANGELOG | + +### Validation (`api/validate/`) + +| Script | Purpose | +|--------|---------| +| `check_repo_health.php` | 118-point health score (9 categories incl. rulesets) | +| `check_composer_deps.php` | Validate enterprise dependency version across all repos | +| `scan_drift.php` | Detect file/config drift from standards | + +### Maintenance (`api/maintenance/`) + +| Script | Purpose | +|--------|---------| +| `rotate_secrets.php` | Audit DEV/DEMO/RS FTP secrets and variables | +| `repo_inventory.php` | Live inventory dashboard posted as GitHub issue | +| `repo_cleanup.php` | 8 cleanup operations (branches, PRs, retired workflows, etc.) | +| `update_version_from_readme.php` | Propagate version across all file headers and badges | +| `setup_labels.php` | Deploy 58-label standard set | + +## CI/CD Pipeline Overview + +The complete automation pipeline runs on every push and pull request. + +```mermaid +flowchart TD + A[Code Push/PR] --> B[Gitea Actions Trigger] + + B --> C[Standards Compliance Check] + B --> D[Security Scanning] + B --> E[Code Quality Analysis] + + C --> C1[File Headers] + C --> C2[Tabs/Spaces Policy] + C --> C3[File Encoding] + C --> C4[Trailing Spaces] + C --> C5[CHANGELOG Format] + + D --> D1[Secret Scanning] + D --> D2[CodeQL Analysis] + D --> D3[Dependency Review] + + E --> E1[PHP Syntax Check] + E --> E2[Shell Script Validation] + E --> E4[Markdown Links] + + C1 --> F{All Checks Pass?} + C2 --> F + C3 --> F + C4 --> F + C5 --> F + D1 --> F + D2 --> F + D3 --> F + E1 --> F + E2 --> F + E4 --> F + + F -->|Yes| G[✓ Build Passes] + F -->|No| H[✗ Build Fails] + + G --> I{Is Main Branch?} + I -->|Yes| J[Trigger Auto-Release] + I -->|No| K[Ready for Merge] + + style A fill:#e1f5ff + style G fill:#c8e6c9 + style H fill:#ffccbc +``` + +> Full diagram set: [docs/visual/cicd-pipeline.md](visual-cicd-pipeline) + +## Bulk Sync Workflow + +`bulk_sync.php` synchronizes standards across all organization repositories with checkpoint recovery. + +```mermaid +flowchart LR + A[bulk_sync.php] --> B{--dry-run?} + B -->|Yes| C[Simulate all operations\nNo API writes\nNo checkpoints written] + B -->|No| D[Execute real sync\nWrite to GitHub API\nCheckpoint after each repo] + + style C fill:#fff9c4 + style D fill:#e1f5ff +``` + +> Full diagram: [docs/visual/bulk-sync-workflow.md](visual-bulk-sync-workflow) + +## Related Documentation + +### Scripts Documentation +- [Maintenance Scripts](..-api-maintenance-index) +- [Release Scripts](..-api-release-index) +- [Automation Scripts](..-api-automation-index) + +### Policy & Strategy +- [Branching Strategy](policy-branching-strategy) +- [Release Management](policy-governance-release-management) + +## Support + +For automation-related issues: +1. Review script documentation in [api/automation/](../../api/automation/) +2. Contact moko-platform maintainers + +--- + +**Last Updated**: 2026-02-26 +**Status**: Production Ready --- -**Last Updated**: 2026-02-26 -**Status**: Production Ready +*Repo: [moko-platform](https://git.mokoconsulting.tech/MokoConsulting/moko-platform) · [moko-platform wiki](https://git.mokoconsulting.tech/MokoConsulting/moko-platform/wiki/Home)* + +| Field | Value | +|---|---| +| Minimum Version | 04.07.00 | +| Platform | all | +| Applies To | moko-platform | + +| Revision | Date | Author | Description | +|---|---|---|---| +| 1.0 | 2026-05-08 | Moko Consulting | Initial version | diff --git a/moko-platform/automation-branch-version-automation.-.-.md b/moko-platform/automation-branch-version-automation.-.-.md index ec7f8de..dea303c 100644 --- a/moko-platform/automation-branch-version-automation.-.-.md +++ b/moko-platform/automation-branch-version-automation.-.-.md @@ -1,339 +1,352 @@ ← [Home](Home) -[![moko-platform](https://img.shields.io/badge/moko-platform-05.00.00-orange)](https://git.mokoconsulting.tech/MokoConsulting/moko-platform) - -> **⚠️ DEPRECATED DOCUMENTATION** -> **Status**: REMOVED — This Python-based automation system has been replaced by PHP scripts. See api/automation/. -> **Last Updated**: 2026-02-10 -> **Current Status**: moko-platform uses PHP-based automation (see [Automation Scripts](..-api-automation-index)) - -# Branch and Version Automation - Comprehensive Guide - -**Document Version**: 1.0.0 -**Last Updated**: 2026-02-10 -**Status**: Production Ready -**Audience**: Developers, DevOps Engineers, Repository Maintainers - -## Overview - -This guide provides comprehensive documentation for the branch and version automation systems deployed across all moko-platform organization repositories via Terraform. - -### Quick Links - -- [Version Automation](#version-automation) -- [Branch Management](#branch-management) -- [Release Automation](#release-automation) -- [Terraform Distribution](#terraform-distribution) -- [Troubleshooting](#troubleshooting) - -## Required Scripts (9 Total) - -All organization repositories automatically receive these scripts: - -| Script | Category | Purpose | Auto-Sync | -|--------|----------|---------|-----------| -| `version_bump_detector.py` | Core Library | Semantic version detection | ✅ | -| `detect_version_bump.py` | Automation | Version bump CLI | ✅ | -| `common.py` | Core Library | Shared utilities | ⚠️ | -| `clean_old_branches.py` | Maintenance | Branch cleanup | ✅ | -| `release_version.py` | Maintenance | Release management | ✅ | -| `unified_release.py` | Release | Release orchestration | ✅ | -| `detect_platform.py` | Release | Platform detection | ✅ | -| `package_extension.py` | Release | Extension packaging | ✅ | -| `test_version_bump_detector.py` | Testing | Unit tests | ✅ | - -## Version Automation - -### Semantic Version Bump Rules - -``` -Breaking change → MAJOR (X.y.z) -New feature → MINOR (x.Y.z) -Bug fix → PATCH (x.y.Z) -Documentation update → PATCH (x.y.Z) -Performance improvement → PATCH (x.y.Z) -Code refactoring → PATCH (x.y.Z) -Dependency update → PATCH (x.y.Z) -Security fix → PATCH (x.y.Z) -``` - -### Quick Start - -**Detect version bump:** -```bash -./api/automation/detect_version_bump.py --file pr_template.md -``` - -**Apply version bump:** -```bash -./api/automation/detect_version_bump.py \ - --text "New feature" \ - --apply \ - --stats -``` - -### Enterprise Features - -- ✅ **Audit Logging**: Complete operation trail in JSON format -- ✅ **Backup/Rollback**: Automatic backup before modifications -- ✅ **SHA-256 Integrity**: File integrity validation -- ✅ **Performance Metrics**: Detailed statistics -- ✅ **Dry-Run Mode**: Preview changes safely - -**Audit Log Location**: `logs/automation/version_bump_*.json` - -### CLI Reference - -```bash -./api/automation/detect_version_bump.py [OPTIONS] - -Input Sources: - --file FILE Read from file - --stdin Read from stdin - --text TEXT Analyze text - --checkboxes TEXT Analyze checkboxes - -Actions: - --apply Apply version bump - --dry-run Preview only - -Options: - --bump-type {major,minor,patch} Override detection - --backup / --no-backup Toggle backup - --audit-log / --no-audit-log Toggle logging - --verbose, -v Verbose output - --json JSON output - --stats Performance stats -``` - -## Branch Management - -### Automated Branch Cleanup - -**List old branches:** -```bash -./api/maintenance/clean_old_branches.py --days 90 --list -``` - -**Delete with dry-run:** -```bash -./api/maintenance/clean_old_branches.py --days 90 --delete --dry-run -``` - -**Actually delete:** -```bash -./api/maintenance/clean_old_branches.py --days 90 --delete --yes -``` - -**Protected Branches** (never deleted): -- `main`, `master`, `dev`, `staging`, `production` - -### Release Version Management - -**Create release:** -```bash -./api/maintenance/release_version.py --version 1.3.0 --yes -``` - -**Update CHANGELOG only:** -```bash -./api/maintenance/release_version.py --version 1.3.0 --changelog-only -``` - -**What it does:** -1. Moves UNRELEASED to versioned section -2. Updates VERSION in headers -3. Creates git tags (optional) -4. Triggers GitHub releases (optional) - -## Release Automation - -### Unified Release - -**Create stable release:** -```bash -./scripts/release/unified_release.py --version 1.3.0 --release-type stable -``` - -**Release candidate:** -```bash -./scripts/release/unified_release.py --version 1.3.0-rc1 --release-type rc -``` - -### Release Types - -| Type | Example | Use Case | -|------|---------|----------| -| `stable` | 1.3.0 | Production | -| `rc` | 1.3.0-rc1 | Release candidate | -| `beta` | 1.3.0-beta1 | Beta testing | -| `alpha` | 1.3.0-alpha1 | Early testing | - -### Platform Detection - -```bash -./scripts/release/detect_platform.py -``` - -**Supported:** Joomla, Dolibarr, WordPress, Python, Node.js, Generic - -### Extension Packaging - -```bash -./scripts/release/package_extension.py --version 1.3.0 -``` - -**Output:** `release/ProjectName-1.3.0.zip` + checksums - -## Terraform Distribution - -### Deployment - -**Automatic:** -```bash -./api/automation/bulk_update_repos.php --yes --set-standards -``` - -**Manual:** -```bash -cd infrastructure/terraform/repository-management -terraform apply -var="github_token=$GH_TOKEN" -``` - -### Configuration Files - -- `infrastructure/terraform/repository-types/default-repository.tf` - Structure definition -- `infrastructure/terraform/repository-management/main.tf` - Distribution config - -## Troubleshooting - -### Version Not Found - -**Error:** `Version not found in README.md` - -**Fix:** Ensure format is `# README - ProjectName (VERSION: 05.00.00)` - -### Permission Denied - -```bash -chmod -R 755 scripts/ -chmod 644 scripts/**/*.py -``` - -### Failed Mid-Operation - -```bash -# Check backup -ls -la .version_bump_backup/ - -# Rollback -cp -r .version_bump_backup/* ./ - -# Retry -./api/automation/detect_version_bump.py --text "Fix" --apply -``` - -### Debug Mode - -```bash -# Verbose output -./api/automation/detect_version_bump.py --verbose --text "..." - -# Check logs -cat logs/automation/version_bump_*.json | jq '.' -``` - -## Integration Patterns - -### Gitea Actions - -```yaml -name: Auto Version Bump -on: - pull_request: - types: [closed] - branches: [main] - -jobs: - version-bump: - if: github.event.pull_request.merged == true - runs-on: ubuntu-latest - steps: - - uses: actions/checkout@v4 - - - name: Apply Version Bump - run: | - ./api/automation/detect_version_bump.py \ - --text "${{ github.event.pull_request.body }}" \ - --apply \ - --stats -``` - -### Pre-commit Hook - -```bash -#!/bin/bash -# .git/hooks/pre-commit - -if git diff --cached --name-only | grep -qE '(\.py|\.md)$'; then - ./api/automation/detect_version_bump.py --validate || { - echo "❌ Version inconsistency" - exit 1 - } -fi -``` - -## Best Practices - -### Version Management - -1. Always run dry-run first -2. Review audit logs regularly -3. Keep backups for 30+ days -4. Use semantic versioning consistently - -### Branch Management - -1. Run cleanup monthly -2. Always dry-run before delete -3. Maintain protected branch list -4. Document exceptions - -### Release Automation - -1. Detect platform before release -2. Test packaging in non-prod -3. Verify checksums -4. Maintain release notes - -## Reference - -### Related Documentation - -- [Terraform Distribution Guide](..-infrastructure-terraform-repository-management-VERSION_BUMP_DISTRIBUTION) -- [Maintenance Scripts](..-api-maintenance-index) -- [Release Scripts](..-api-release-index) -- [Branching Strategy](policy-branching-strategy) - -### External Resources - -- [Semantic Versioning](https://semver.org/) -- [Keep a Changelog](https://keepachangelog.com/) -- [Conventional Commits](https://www.conventionalcommits.org/) - -## Support - -**Getting Help:** -1. Check this documentation -2. Review troubleshooting section -3. Check audit logs: `logs/automation/*.json` -4. Contact moko-platform maintainers - -**Reporting Issues:** -Include: script name, command, error message, audit log, context - +[![moko-platform](https://img.shields.io/badge/moko-platform-04.06.00-orange)](https://git.mokoconsulting.tech/MokoConsulting/moko-platform) + +> **⚠️ DEPRECATED DOCUMENTATION** +> **Status**: REMOVED — This Python-based automation system has been replaced by PHP scripts. See api/automation/. +> **Last Updated**: 2026-02-10 +> **Current Status**: moko-platform uses PHP-based automation (see [Automation Scripts](..-api-automation-index)) + +# Branch and Version Automation - Comprehensive Guide + +**Document Version**: 1.0.0 +**Last Updated**: 2026-02-10 +**Status**: Production Ready +**Audience**: Developers, DevOps Engineers, Repository Maintainers + +## Overview + +This guide provides comprehensive documentation for the branch and version automation systems deployed across all moko-platform organization repositories via Terraform. + +### Quick Links + +- [Version Automation](#version-automation) +- [Branch Management](#branch-management) +- [Release Automation](#release-automation) +- [Terraform Distribution](#terraform-distribution) +- [Troubleshooting](#troubleshooting) + +## Required Scripts (9 Total) + +All organization repositories automatically receive these scripts: + +| Script | Category | Purpose | Auto-Sync | +|--------|----------|---------|-----------| +| `version_bump_detector.py` | Core Library | Semantic version detection | ✅ | +| `detect_version_bump.py` | Automation | Version bump CLI | ✅ | +| `common.py` | Core Library | Shared utilities | ⚠️ | +| `clean_old_branches.py` | Maintenance | Branch cleanup | ✅ | +| `release_version.py` | Maintenance | Release management | ✅ | +| `unified_release.py` | Release | Release orchestration | ✅ | +| `detect_platform.py` | Release | Platform detection | ✅ | +| `package_extension.py` | Release | Extension packaging | ✅ | +| `test_version_bump_detector.py` | Testing | Unit tests | ✅ | + +## Version Automation + +### Semantic Version Bump Rules + +``` +Breaking change → MAJOR (X.y.z) +New feature → MINOR (x.Y.z) +Bug fix → PATCH (x.y.Z) +Documentation update → PATCH (x.y.Z) +Performance improvement → PATCH (x.y.Z) +Code refactoring → PATCH (x.y.Z) +Dependency update → PATCH (x.y.Z) +Security fix → PATCH (x.y.Z) +``` + +### Quick Start + +**Detect version bump:** +```bash +./api/automation/detect_version_bump.py --file pr_template.md +``` + +**Apply version bump:** +```bash +./api/automation/detect_version_bump.py \ + --text "New feature" \ + --apply \ + --stats +``` + +### Enterprise Features + +- ✅ **Audit Logging**: Complete operation trail in JSON format +- ✅ **Backup/Rollback**: Automatic backup before modifications +- ✅ **SHA-256 Integrity**: File integrity validation +- ✅ **Performance Metrics**: Detailed statistics +- ✅ **Dry-Run Mode**: Preview changes safely + +**Audit Log Location**: `logs/automation/version_bump_*.json` + +### CLI Reference + +```bash +./api/automation/detect_version_bump.py [OPTIONS] + +Input Sources: + --file FILE Read from file + --stdin Read from stdin + --text TEXT Analyze text + --checkboxes TEXT Analyze checkboxes + +Actions: + --apply Apply version bump + --dry-run Preview only + +Options: + --bump-type {major,minor,patch} Override detection + --backup / --no-backup Toggle backup + --audit-log / --no-audit-log Toggle logging + --verbose, -v Verbose output + --json JSON output + --stats Performance stats +``` + +## Branch Management + +### Automated Branch Cleanup + +**List old branches:** +```bash +./api/maintenance/clean_old_branches.py --days 90 --list +``` + +**Delete with dry-run:** +```bash +./api/maintenance/clean_old_branches.py --days 90 --delete --dry-run +``` + +**Actually delete:** +```bash +./api/maintenance/clean_old_branches.py --days 90 --delete --yes +``` + +**Protected Branches** (never deleted): +- `main`, `master`, `dev`, `staging`, `production` + +### Release Version Management + +**Create release:** +```bash +./api/maintenance/release_version.py --version 1.3.0 --yes +``` + +**Update CHANGELOG only:** +```bash +./api/maintenance/release_version.py --version 1.3.0 --changelog-only +``` + +**What it does:** +1. Moves UNRELEASED to versioned section +2. Updates VERSION in headers +3. Creates git tags (optional) +4. Triggers GitHub releases (optional) + +## Release Automation + +### Unified Release + +**Create stable release:** +```bash +./scripts/release/unified_release.py --version 1.3.0 --release-type stable +``` + +**Release candidate:** +```bash +./scripts/release/unified_release.py --version 1.3.0-rc1 --release-type rc +``` + +### Release Types + +| Type | Example | Use Case | +|------|---------|----------| +| `stable` | 1.3.0 | Production | +| `rc` | 1.3.0-rc1 | Release candidate | +| `beta` | 1.3.0-beta1 | Beta testing | +| `alpha` | 1.3.0-alpha1 | Early testing | + +### Platform Detection + +```bash +./scripts/release/detect_platform.py +``` + +**Supported:** Joomla, Dolibarr, WordPress, Python, Node.js, Generic + +### Extension Packaging + +```bash +./scripts/release/package_extension.py --version 1.3.0 +``` + +**Output:** `release/ProjectName-1.3.0.zip` + checksums + +## Terraform Distribution + +### Deployment + +**Automatic:** +```bash +./api/automation/bulk_update_repos.php --yes --set-standards +``` + +**Manual:** +```bash +cd infrastructure/terraform/repository-management +terraform apply -var="github_token=$GH_TOKEN" +``` + +### Configuration Files + +- `infrastructure/terraform/repository-types/default-repository.tf` - Structure definition +- `infrastructure/terraform/repository-management/main.tf` - Distribution config + +## Troubleshooting + +### Version Not Found + +**Error:** `Version not found in README.md` + +**Fix:** Ensure format is `# README - ProjectName (VERSION: 04.06.00)` + +### Permission Denied + +```bash +chmod -R 755 scripts/ +chmod 644 scripts/**/*.py +``` + +### Failed Mid-Operation + +```bash +# Check backup +ls -la .version_bump_backup/ + +# Rollback +cp -r .version_bump_backup/* ./ + +# Retry +./api/automation/detect_version_bump.py --text "Fix" --apply +``` + +### Debug Mode + +```bash +# Verbose output +./api/automation/detect_version_bump.py --verbose --text "..." + +# Check logs +cat logs/automation/version_bump_*.json | jq '.' +``` + +## Integration Patterns + +### Gitea Actions + +```yaml +name: Auto Version Bump +on: + pull_request: + types: [closed] + branches: [main] + +jobs: + version-bump: + if: github.event.pull_request.merged == true + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v4 + + - name: Apply Version Bump + run: | + ./api/automation/detect_version_bump.py \ + --text "${{ github.event.pull_request.body }}" \ + --apply \ + --stats +``` + +### Pre-commit Hook + +```bash +#!/bin/bash +# .git/hooks/pre-commit + +if git diff --cached --name-only | grep -qE '(\.py|\.md)$'; then + ./api/automation/detect_version_bump.py --validate || { + echo "❌ Version inconsistency" + exit 1 + } +fi +``` + +## Best Practices + +### Version Management + +1. Always run dry-run first +2. Review audit logs regularly +3. Keep backups for 30+ days +4. Use semantic versioning consistently + +### Branch Management + +1. Run cleanup monthly +2. Always dry-run before delete +3. Maintain protected branch list +4. Document exceptions + +### Release Automation + +1. Detect platform before release +2. Test packaging in non-prod +3. Verify checksums +4. Maintain release notes + +## Reference + +### Related Documentation + +- [Terraform Distribution Guide](..-infrastructure-terraform-repository-management-VERSION_BUMP_DISTRIBUTION) +- [Maintenance Scripts](..-api-maintenance-index) +- [Release Scripts](..-api-release-index) +- [Branching Strategy](policy-branching-strategy) + +### External Resources + +- [Semantic Versioning](https://semver.org/) +- [Keep a Changelog](https://keepachangelog.com/) +- [Conventional Commits](https://www.conventionalcommits.org/) + +## Support + +**Getting Help:** +1. Check this documentation +2. Review troubleshooting section +3. Check audit logs: `logs/automation/*.json` +4. Contact moko-platform maintainers + +**Reporting Issues:** +Include: script name, command, error message, audit log, context + +--- + +**Document Version**: 1.0.0 +**Next Review**: 2026-03-10 +**Maintainer**: moko-platform Team --- -**Document Version**: 1.0.0 -**Next Review**: 2026-03-10 -**Maintainer**: moko-platform Team +*Repo: [moko-platform](https://git.mokoconsulting.tech/MokoConsulting/moko-platform) · [moko-platform wiki](https://git.mokoconsulting.tech/MokoConsulting/moko-platform/wiki/Home)* + +| Field | Value | +|---|---| +| Minimum Version | 04.07.00 | +| Platform | all | +| Applies To | All repositories | + +| Revision | Date | Author | Description | +|---|---|---|---| +| 1.0 | 2026-05-08 | Moko Consulting | Initial version | diff --git a/moko-platform/automation-push-files.-.-.md b/moko-platform/automation-push-files.-.-.md index a4a77b6..c7127ae 100644 --- a/moko-platform/automation-push-files.-.-.md +++ b/moko-platform/automation-push-files.-.-.md @@ -1,6 +1,6 @@ ← [Home](Home) -[![moko-platform](https://img.shields.io/badge/moko-platform-05.00.00-orange)](https://git.mokoconsulting.tech/MokoConsulting/moko-platform) +[![moko-platform](https://img.shields.io/badge/moko-platform-04.06.00-orange)](https://git.mokoconsulting.tech/MokoConsulting/moko-platform) # Push Files @@ -41,3 +41,16 @@ php api/automation/push_files.php --repos MokoCRM --files "LICENSE" --yes --no-i - Cross-links the tracking issue to the PR in the Development sidebar - Assigns `jmiller` to both PR and issue - Applies standard labels: `standards-update`, `mokostandards`, `type: chore`, `automation` +--- + +*Repo: [moko-platform](https://git.mokoconsulting.tech/MokoConsulting/moko-platform) · [moko-platform wiki](https://git.mokoconsulting.tech/MokoConsulting/moko-platform/wiki/Home)* + +| Field | Value | +|---|---| +| Minimum Version | 04.07.00 | +| Platform | all | +| Applies To | All repositories | + +| Revision | Date | Author | Description | +|---|---|---|---| +| 1.0 | 2026-05-08 | Moko Consulting | Initial version | diff --git a/moko-platform/automation-repo-cleanup.-.-.md b/moko-platform/automation-repo-cleanup.-.-.md index 0af7349..633314a 100644 --- a/moko-platform/automation-repo-cleanup.-.-.md +++ b/moko-platform/automation-repo-cleanup.-.-.md @@ -1,6 +1,6 @@ ← [Home](Home) -[![moko-platform](https://img.shields.io/badge/moko-platform-05.00.00-orange)](https://git.mokoconsulting.tech/MokoConsulting/moko-platform) +[![moko-platform](https://img.shields.io/badge/moko-platform-04.06.00-orange)](https://git.mokoconsulting.tech/MokoConsulting/moko-platform) # Repository Cleanup @@ -97,3 +97,16 @@ php api/automation/repo_cleanup.php --repos MokoCRM --yes | `--dry-run` | Preview without making changes | | `--yes` | Auto-confirm prompts | | `--json` | Output results as JSON | +--- + +*Repo: [moko-platform](https://git.mokoconsulting.tech/MokoConsulting/moko-platform) · [moko-platform wiki](https://git.mokoconsulting.tech/MokoConsulting/moko-platform/wiki/Home)* + +| Field | Value | +|---|---| +| Minimum Version | 04.07.00 | +| Platform | all | +| Applies To | All repositories | + +| Revision | Date | Author | Description | +|---|---|---|---| +| 1.0 | 2026-05-08 | Moko Consulting | Initial version | diff --git a/moko-platform/client-repos.-.-.-.md b/moko-platform/client-repos.-.-.-.md index f346358..e9dda39 100644 --- a/moko-platform/client-repos.-.-.-.md +++ b/moko-platform/client-repos.-.-.-.md @@ -136,3 +136,16 @@ Client sites are deployed via: - [WORKFLOW_STANDARDS](WORKFLOW_STANDARDS) -- CI/CD workflow conventions - [ARCHITECTURE](ARCHITECTURE) -- Platform scripts architecture - [JOOMLA_SYNC](JOOMLA_SYNC) -- Joomla extension sync between servers +--- + +*Repo: [moko-platform](https://git.mokoconsulting.tech/MokoConsulting/moko-platform) · [moko-platform wiki](https://git.mokoconsulting.tech/MokoConsulting/moko-platform/wiki/Home)* + +| Field | Value | +|---|---| +| Minimum Version | 04.07.00 | +| Platform | joomla | +| Applies To | Client repositories | + +| Revision | Date | Author | Description | +|---|---|---|---| +| 1.0 | 2026-05-09 | Moko Consulting | Initial version | diff --git a/moko-platform/standards-mokostandards-file-spec.-.-.md b/moko-platform/standards-mokostandards-file-spec.-.-.md index bdef611..1da2916 100644 --- a/moko-platform/standards-mokostandards-file-spec.-.-.md +++ b/moko-platform/standards-mokostandards-file-spec.-.-.md @@ -243,3 +243,16 @@ A missing or invalid `.mokostandards` file is a **compliance failure**. | **Makefile** | Can source `` for consistent `make` targets | | **moko-validate** | Validates the XML against the XSD and checks required fields | | **detectPlatform()** | Falls back to name/topic heuristics only when `.mokostandards` is missing or unparseable | +--- + +*Repo: [moko-platform](https://git.mokoconsulting.tech/MokoConsulting/moko-platform) · [moko-platform wiki](https://git.mokoconsulting.tech/MokoConsulting/moko-platform/wiki/Home)* + +| Field | Value | +|---|---| +| Minimum Version | 04.07.00 | +| Platform | all | +| Applies To | All repositories | + +| Revision | Date | Author | Description | +|---|---|---|---| +| 1.0 | 2026-05-08 | Moko Consulting | Initial version | diff --git a/moko-platform/workflows-README.-.-.md b/moko-platform/workflows-README.-.-.md index c62e0a3..a18f86a 100644 --- a/moko-platform/workflows-README.-.-.md +++ b/moko-platform/workflows-README.-.-.md @@ -1,63 +1,76 @@ ← [Home](Home) -[![moko-platform](https://img.shields.io/badge/moko-platform-05.00.00-orange)](https://git.mokoconsulting.tech/MokoConsulting/moko-platform) +[![moko-platform](https://img.shields.io/badge/moko-platform-04.06.00-orange)](https://git.mokoconsulting.tech/MokoConsulting/moko-platform) + +# Workflow Templates — Secondary Reference + +**Status**: Active | **Version**: 04.06.00 | **Effective**: 2026-05-05 + +> **Canonical documentation**: [WORKFLOW_STANDARDS.md](WORKFLOW_STANDARDS) is the primary reference for workflow standards, inventory, and architecture. This file provides supplementary context only. + +## Architecture + +Workflow templates live in their respective **template repositories**, not in moko-platform: + +- **moko-platform-Template-Joomla** — Joomla extension workflows +- **moko-platform-Template-Dolibarr** — Dolibarr module workflows +- **moko-platform-Template-Generic** — Generic project workflows +- **moko-platform-Template-Client** — Client site workflows + +The **sync engine** clones the appropriate template repo at runtime and applies workflows to target repositories. There is no local `templates/workflows/` directory to copy from. + +## How Workflows Reach Repos + +1. New repos are created from a template repo (e.g., `moko-platform-Template-Joomla`), which includes `.gitea/workflows/` pre-populated. +2. Existing repos receive workflow updates via the bulk-sync engine, which clones the template repo, compares, and pushes changes. +3. All workflows run from `.gitea/workflows/` only — Gitea Actions does not execute workflows from `.gitea/workflows/`. + +## Important Notes + +- Releases use the 5-stream tag system (`stable`, `release-candidate`, `beta`, `alpha`, `development`). See [Release System](release-system). +- All workflows require SPDX license headers (GPL-3.0-or-later). +- Pin action versions (use `@v4`, not `@main`). + +## Related Documentation + +- [WORKFLOW_STANDARDS.md](WORKFLOW_STANDARDS) — Canonical workflow reference +- [Workflow Architecture](workflow-architecture) +- [Workflow Inventory](workflow-inventory) +- [Reusable Workflows](reusable-workflows) +- [Release System](release-system) +- [Build System](build-system-README) +- [Health Scoring System](policy-health-scoring) + +## Metadata + +| Field | Value | +|---|---| +| Document | Workflow Templates — Secondary Reference | +| Path | /docs/workflows/README.md | +| Repository | https://git.mokoconsulting.tech/MokoConsulting/moko-platform | +| Owner | Moko Consulting | +| Status | Active | +| Version | 04.06.00 | +| Effective | 2026-05-05 | + +## Version History + +| Version | Date | Changes | +|---|---|---| +| 04.06.00 | 2026-05-05 | Rewritten to reflect current architecture: templates live in template repos, sync engine clones at runtime, removed stale `templates/workflows/` references | +| 04.00.04 | 2026-02-08 | Consolidated workflow templates | +| 04.00.04 | 2026-01-07 | Added public workflow templates documentation | +| 01.00.00 | 2026-01-07 | Initial comprehensive workflow documentation | +--- -# Workflow Templates — Secondary Reference - -**Status**: Active | **Version**: 05.00.00 | **Effective**: 2026-05-05 - -> **Canonical documentation**: [WORKFLOW_STANDARDS.md](WORKFLOW_STANDARDS) is the primary reference for workflow standards, inventory, and architecture. This file provides supplementary context only. - -## Architecture - -Workflow templates live in their respective **template repositories**, not in moko-platform: - -- **moko-platform-Template-Joomla** — Joomla extension workflows -- **moko-platform-Template-Dolibarr** — Dolibarr module workflows -- **moko-platform-Template-Generic** — Generic project workflows -- **moko-platform-Template-Client** — Client site workflows - -The **sync engine** clones the appropriate template repo at runtime and applies workflows to target repositories. There is no local `templates/workflows/` directory to copy from. - -## How Workflows Reach Repos - -1. New repos are created from a template repo (e.g., `moko-platform-Template-Joomla`), which includes `.gitea/workflows/` pre-populated. -2. Existing repos receive workflow updates via the bulk-sync engine, which clones the template repo, compares, and pushes changes. -3. All workflows run from `.gitea/workflows/` only — Gitea Actions does not execute workflows from `.gitea/workflows/`. - -## Important Notes - -- Releases use the 5-stream tag system (`stable`, `release-candidate`, `beta`, `alpha`, `development`). See [Release System](release-system). -- All workflows require SPDX license headers (GPL-3.0-or-later). -- Pin action versions (use `@v4`, not `@main`). - -## Related Documentation - -- [WORKFLOW_STANDARDS.md](WORKFLOW_STANDARDS) — Canonical workflow reference -- [Workflow Architecture](workflow-architecture) -- [Workflow Inventory](workflow-inventory) -- [Reusable Workflows](reusable-workflows) -- [Release System](release-system) -- [Build System](build-system-README) -- [Health Scoring System](policy-health-scoring) - -## Metadata +*Repo: [moko-platform](https://git.mokoconsulting.tech/MokoConsulting/moko-platform) · [moko-platform wiki](https://git.mokoconsulting.tech/MokoConsulting/moko-platform/wiki/Home)* | Field | Value | |---|---| -| Document | Workflow Templates — Secondary Reference | -| Path | /docs/workflows/README.md | -| Repository | https://git.mokoconsulting.tech/MokoConsulting/moko-platform | -| Owner | Moko Consulting | -| Status | Active | -| Version | 05.00.00 | -| Effective | 2026-05-05 | +| Minimum Version | 04.07.00 | +| Platform | all | +| Applies To | All repositories | -## Version History - -| Version | Date | Changes | -|---|---|---| -| 05.00.00 | 2026-05-05 | Rewritten to reflect current architecture: templates live in template repos, sync engine clones at runtime, removed stale `templates/workflows/` references | -| 04.00.04 | 2026-02-08 | Consolidated workflow templates | -| 04.00.04 | 2026-01-07 | Added public workflow templates documentation | -| 01.00.00 | 2026-01-07 | Initial comprehensive workflow documentation | +| Revision | Date | Author | Description | +|---|---|---|---| +| 1.0 | 2026-05-08 | Moko Consulting | Initial version | diff --git a/moko-platform/workflows-auto-release.-.-.md b/moko-platform/workflows-auto-release.-.-.md index d155dd5..47e66ed 100644 --- a/moko-platform/workflows-auto-release.-.-.md +++ b/moko-platform/workflows-auto-release.-.-.md @@ -1,90 +1,103 @@ ← [Home](Home) -[![moko-platform](https://img.shields.io/badge/moko-platform-05.00.00-orange)](https://git.mokoconsulting.tech/MokoConsulting/moko-platform) - -# Auto Release - -Creates or updates a GitHub Release on every push to main. Uses **major-only tags** (`vXX`) — one release per major version, with all minor+patch versions appending notes and assets to the same release. - -## Platform-Specific Pipelines - -### Generic Repos - -1. Reads `VERSION:` from README.md FILE INFORMATION block (e.g., `05.00.00`) -2. Extracts major version (e.g., `04`) -3. Creates or updates the `v04` tag on the release commit -4. Creates or updates the `v04` GitHub Release, appending changelog notes for this version -5. Auto-bumps patch version with `[skip ci]` commit -6. Auto-creates `version/XX` archive branch - -### Joomla Repos (waas-component) - -Joomla repos do **not** use FTP deploy. Distribution is via GitHub Release ZIPs. - -1. Reads `VERSION:` from README.md FILE INFORMATION block -2. Builds installable ZIP from `src/` directory -3. Computes SHA-256 hash of the ZIP -4. Uploads ZIP as an asset to the `vXX` GitHub Release (e.g., `com_myextension-01.02.03.zip`) -5. Updates `updates.xml` with the stable entry: version, download URL, and SHA-256 hash -6. Creates or updates the `vXX` tag and release, appending changelog notes -7. Auto-bumps patch version with `[skip ci]` commit -8. Auto-creates `version/XX` archive branch - -### Dolibarr Repos (crm-module, crm-platform) - -1. Reads `VERSION:` from README.md FILE INFORMATION block -2. Updates `$this->version` in `mod*.class.php` to the real version -3. Updates `update.txt` with the stable version string -4. Creates or updates the `vXX` tag and release, appending changelog notes -5. Auto-bumps patch version with `[skip ci]` commit -6. Auto-creates `version/XX` archive branch - -## Triggers - -- Push to `main` or `master` -- Skips commits by `gitea-actions[bot]` and commits with `[skip ci]` - -## Version Lifecycle - -| Phase | Branch | Module Version | Release? | -|-------|--------|---------------|----------| -| Development | `dev/**` | `XX.YY.00` (patch 00 = dev) | No | -| Alpha (optional) | `alpha/**` | `XX.YY.ZZ` | `alpha` tag release | -| Beta (optional) | `beta/**` | `XX.YY.ZZ` | `beta` tag release | -| Release Candidate | `rc/**` | `XX.YY.ZZ` (patch >= 01) | `release-candidate` tag (draft release created on RC branch creation) | -| Merge to main | `main` | Real version (e.g., `01.02.01`) | Yes — `vXX` tag + release | -| Auto-bump | `main` | Auto-incremented patch | No (skipped by `[skip ci]`) | - -**Note**: Alpha and beta stages are optional. Dev can go directly to rc when not needed. - -## Release Tags - -Each stability level has its own GitHub Release tag: - -| Tag | Stability | Source | -|-----|-----------|--------| -| `development` | Development | `dev/**` branches | -| `alpha` | Alpha | `alpha/**` branches | -| `beta` | Beta | `beta/**` branches | -| `release-candidate` | RC | `rc/**` branches | -| `vXX` | Stable production | `main` (major only, e.g., `v04`) | - -- The `vXX` production tag is **major only** — one GitHub Release per major version -- All minor+patch versions append release notes and ZIP assets to the same `vXX` release -- No minor or patch production tags are created -- Pre-release tags are updated in-place per stability level - -## Stream Tags (v2)Releases use stream-based git tags, NOT version numbers:- `stable` — production release- `release-candidate` — RC testing- `beta` — feature-complete stability testing- `alpha` — early testing- `development` — unstable dev buildsTo trigger a release, push the appropriate stream tag: `git tag -f stable && git push origin stable --force`### Cascade LogicEach stability level cascades to all lower levels in updates.xml:- **stable** → updates development, alpha, beta, rc, stable- **rc** → updates development, alpha, beta, rc- **beta** → updates development, alpha, beta- **alpha** → updates development, alpha- **development** → updates development only### SHA-256 Rules- Never leave `` empty — Joomla fails checksum verification on empty tags- Omit the `` tag entirely if no hash is available- Always set SHA when building a package### creationDateAlways update `` whenever version is bumped — in the manifest AND in updates.xml.### Auto-DetectionThe release workflow (`release.yml`) is fully generic:- `GITEA_REPO` derived from `github.event.repository.name`- `EXT_ELEMENT` auto-detected from the Joomla manifest `` tag- Falls back to manifest filename, then repo name (lowercased)- No per-repo customization needed### Version History (Stable Releases)Stable releases keep up to 5 previous versions in the Gitea release body. -## Requirements - -- `secrets.GH_TOKEN` with `contents: write` permission -- `VERSION:` field in README.md FILE INFORMATION block -- `.mokostandards` file with `platform:` field (`joomla`, `dolibarr`, or `generic`) - -## Changelog Extraction - -The workflow extracts release notes from `CHANGELOG.md` by finding the section header that matches the version number. If no match is found, it uses `"Release {VERSION}"` as the fallback. - -## Draft Release (RC Branches) - +[![moko-platform](https://img.shields.io/badge/moko-platform-04.06.00-orange)](https://git.mokoconsulting.tech/MokoConsulting/moko-platform) + +# Auto Release + +Creates or updates a GitHub Release on every push to main. Uses **major-only tags** (`vXX`) — one release per major version, with all minor+patch versions appending notes and assets to the same release. + +## Platform-Specific Pipelines + +### Generic Repos + +1. Reads `VERSION:` from README.md FILE INFORMATION block (e.g., `04.06.00`) +2. Extracts major version (e.g., `04`) +3. Creates or updates the `v04` tag on the release commit +4. Creates or updates the `v04` GitHub Release, appending changelog notes for this version +5. Auto-bumps patch version with `[skip ci]` commit +6. Auto-creates `version/XX` archive branch + +### Joomla Repos (waas-component) + +Joomla repos do **not** use FTP deploy. Distribution is via GitHub Release ZIPs. + +1. Reads `VERSION:` from README.md FILE INFORMATION block +2. Builds installable ZIP from `src/` directory +3. Computes SHA-256 hash of the ZIP +4. Uploads ZIP as an asset to the `vXX` GitHub Release (e.g., `com_myextension-01.02.03.zip`) +5. Updates `updates.xml` with the stable entry: version, download URL, and SHA-256 hash +6. Creates or updates the `vXX` tag and release, appending changelog notes +7. Auto-bumps patch version with `[skip ci]` commit +8. Auto-creates `version/XX` archive branch + +### Dolibarr Repos (crm-module, crm-platform) + +1. Reads `VERSION:` from README.md FILE INFORMATION block +2. Updates `$this->version` in `mod*.class.php` to the real version +3. Updates `update.txt` with the stable version string +4. Creates or updates the `vXX` tag and release, appending changelog notes +5. Auto-bumps patch version with `[skip ci]` commit +6. Auto-creates `version/XX` archive branch + +## Triggers + +- Push to `main` or `master` +- Skips commits by `gitea-actions[bot]` and commits with `[skip ci]` + +## Version Lifecycle + +| Phase | Branch | Module Version | Release? | +|-------|--------|---------------|----------| +| Development | `dev/**` | `XX.YY.00` (patch 00 = dev) | No | +| Alpha (optional) | `alpha/**` | `XX.YY.ZZ` | `alpha` tag release | +| Beta (optional) | `beta/**` | `XX.YY.ZZ` | `beta` tag release | +| Release Candidate | `rc/**` | `XX.YY.ZZ` (patch >= 01) | `release-candidate` tag (draft release created on RC branch creation) | +| Merge to main | `main` | Real version (e.g., `01.02.01`) | Yes — `vXX` tag + release | +| Auto-bump | `main` | Auto-incremented patch | No (skipped by `[skip ci]`) | + +**Note**: Alpha and beta stages are optional. Dev can go directly to rc when not needed. + +## Release Tags + +Each stability level has its own GitHub Release tag: + +| Tag | Stability | Source | +|-----|-----------|--------| +| `development` | Development | `dev/**` branches | +| `alpha` | Alpha | `alpha/**` branches | +| `beta` | Beta | `beta/**` branches | +| `release-candidate` | RC | `rc/**` branches | +| `vXX` | Stable production | `main` (major only, e.g., `v04`) | + +- The `vXX` production tag is **major only** — one GitHub Release per major version +- All minor+patch versions append release notes and ZIP assets to the same `vXX` release +- No minor or patch production tags are created +- Pre-release tags are updated in-place per stability level + +## Stream Tags (v2)Releases use stream-based git tags, NOT version numbers:- `stable` — production release- `release-candidate` — RC testing- `beta` — feature-complete stability testing- `alpha` — early testing- `development` — unstable dev buildsTo trigger a release, push the appropriate stream tag: `git tag -f stable && git push origin stable --force`### Cascade LogicEach stability level cascades to all lower levels in updates.xml:- **stable** → updates development, alpha, beta, rc, stable- **rc** → updates development, alpha, beta, rc- **beta** → updates development, alpha, beta- **alpha** → updates development, alpha- **development** → updates development only### SHA-256 Rules- Never leave `` empty — Joomla fails checksum verification on empty tags- Omit the `` tag entirely if no hash is available- Always set SHA when building a package### creationDateAlways update `` whenever version is bumped — in the manifest AND in updates.xml.### Auto-DetectionThe release workflow (`release.yml`) is fully generic:- `GITEA_REPO` derived from `github.event.repository.name`- `EXT_ELEMENT` auto-detected from the Joomla manifest `` tag- Falls back to manifest filename, then repo name (lowercased)- No per-repo customization needed### Version History (Stable Releases)Stable releases keep up to 5 previous versions in the Gitea release body. +## Requirements + +- `secrets.GH_TOKEN` with `contents: write` permission +- `VERSION:` field in README.md FILE INFORMATION block +- `.mokostandards` file with `platform:` field (`joomla`, `dolibarr`, or `generic`) + +## Changelog Extraction + +The workflow extracts release notes from `CHANGELOG.md` by finding the section header that matches the version number. If no match is found, it uses `"Release {VERSION}"` as the fallback. + +## Draft Release (RC Branches) + When an `rc/**` branch is created, the branch tracking system auto-creates a **draft** GitHub Release for the `vXX` major version. This draft is later published by `auto-release.yml` when the RC merges to main. See [Dev Branch Tracking](dev-branch-tracking) for details. +--- + +*Repo: [moko-platform](https://git.mokoconsulting.tech/MokoConsulting/moko-platform) · [moko-platform wiki](https://git.mokoconsulting.tech/MokoConsulting/moko-platform/wiki/Home)* + +| Field | Value | +|---|---| +| Minimum Version | 04.07.00 | +| Platform | all | +| Applies To | All repositories | + +| Revision | Date | Author | Description | +|---|---|---|---| +| 1.0 | 2026-05-08 | Moko Consulting | Initial version | diff --git a/moko-platform/workflows-branch-protection.-.-.md b/moko-platform/workflows-branch-protection.-.-.md index 6af5d53..e305d10 100644 --- a/moko-platform/workflows-branch-protection.-.-.md +++ b/moko-platform/workflows-branch-protection.-.-.md @@ -1,213 +1,226 @@ ← [Home](Home) -[![moko-platform](https://img.shields.io/badge/moko-platform-05.00.00-orange)](https://git.mokoconsulting.tech/MokoConsulting/moko-platform) - -# Branch Protection Setup Workflow - -**Status**: ✅ Active | **Version**: 01.00.00 | **Last Updated**: 2026-05-07 - -## Table of Contents - -- [Overview](#overview) -- [Protection Rules](#protection-rules) -- [Override Authority](#override-authority) -- [Workflow Triggers](#workflow-triggers) -- [Configuration](#configuration) -- [Excluded Repositories](#excluded-repositories) -- [Usage](#usage) -- [Troubleshooting](#troubleshooting) -- [Related Documentation](#related-documentation) - ---- - -## Overview - -The **Branch Protection Setup** workflow applies standardised branch protection rules to all governed repositories in the MokoConsulting organization. It runs from the **moko-platform** repository and uses the Gitea API to create or update protection rules across repos. - -### Purpose - -- **Consistency**: Uniform branch protection across all repositories -- **Drift Prevention**: Weekly scheduled runs enforce rules even if manually changed -- **Centralised Management**: Single workflow controls protection for the entire organization -- **Override Authority**: `jmiller` has full override capability on all branches - -### Key Features - -✅ **Idempotent**: Deletes and recreates rules to avoid update conflicts -✅ **Weekly Enforcement**: Scheduled every Monday at 02:00 UTC -✅ **Manual Dispatch**: Target specific repos or run against all -✅ **Dry Run Mode**: Preview changes without applying -✅ **Centralised**: Lives in moko-platform, applies to all governed repos - ---- - -## Protection Rules - -### Rule Summary - -| Branch | Push | Push Whitelist | Force Push | Force Push Whitelist | Block Rejected Reviews | Priority | -|--------|------|---------------|------------|---------------------|----------------------|----------| -| `main` | Whitelist | jmiller | Whitelist | jmiller | Yes | 1 | -| `dev` | Open | — | Whitelist | jmiller | No | 2 | -| `rc/*` | Open | — | Whitelist | jmiller | No | 3 | -| `beta/*` | Open | — | Whitelist | jmiller | No | 4 | -| `alpha/*` | Open | — | Whitelist | jmiller | No | 5 | - -### Rule Details - -#### `main` (Priority 1 — Strictest) - -- **Push**: Restricted to whitelist (`jmiller` only) -- **Force Push**: Restricted to whitelist (`jmiller` only) -- **Block on Rejected Reviews**: Yes — prevents merging PRs with rejected reviews -- **Dismiss Stale Approvals**: Yes — new commits invalidate previous approvals -- **Required Approvals**: 0 (solo developer workflow) - -#### `dev` (Priority 2) - -- **Push**: Open to all collaborators -- **Force Push**: Restricted to `jmiller` only -- **Block on Rejected Reviews**: No -- **Purpose**: Development integration branch — needs open push for cascade workflow and CI bots - -#### `rc/*`, `beta/*`, `alpha/*` (Priority 3-5) - -- **Push**: Open to all collaborators -- **Force Push**: Restricted to `jmiller` only -- **Block on Rejected Reviews**: No -- **Purpose**: Pre-release channels — CI workflows push version bumps and package builds directly - ---- - -## Override Authority - -**`jmiller`** has full override authority across all branches: - -- Can push directly to `main` (bypassing PR requirement) -- Can force-push to any branch when needed (emergency fixes, history cleanup) -- Is the only user in force-push whitelists on all branches - -This ensures the organization owner can always intervene in emergencies without being blocked by protection rules. - ---- - -## Workflow Triggers - -| Trigger | Condition | -|---------|-----------| -| `schedule` | Every Monday at 02:00 UTC (drift enforcement) | -| `workflow_dispatch` | Manual — supports `dry_run` and `repos` inputs | - -### Inputs - -| Input | Type | Default | Description | -|-------|------|---------|-------------| -| `dry_run` | boolean | `false` | Preview mode — logs what would change without applying | -| `repos` | string | `""` (all) | Comma-separated repo names to target (empty = all governed repos) | - ---- - -## Configuration - -### Environment Variables - -| Variable | Value | Description | -|----------|-------|-------------| -| `GITEA_URL` | `https://git.mokoconsulting.tech` | Gitea instance URL | -| `GITEA_ORG` | `MokoConsulting` | Organization name | - -### Secrets - -| Secret | Required | Description | -|--------|----------|-------------| -| `GA_TOKEN` | Yes | Gitea API token with admin/repo permissions | - ---- - -## Excluded Repositories - -The following repos are excluded from protection rule application: - -| Repository | Reason | -|-----------|--------| -| `gitea-org-config` | Platform infrastructure | -| `org-profile` | Platform infrastructure | -| `gitea-private` | Platform infrastructure | -| `gitea-server-setup` | Platform infrastructure | -| `moko-platform` | Standards repository | -| `moko-platform` | Standards repository | -| `MokoTesting` | Testing infrastructure | -| `moko-platform-Template-*` | Template repositories | -| `MokoDoliProjTemplate` | Template repository | - ---- - -## Usage - -### Apply to All Repos - -Trigger the workflow manually with default inputs (no dry run, all repos). - -### Apply to Specific Repos - -``` -repos: MokoOnyx,MokoJoomla,MokoJGDPC -``` - -### Preview Mode - -Set `dry_run: true` to see which rules would be applied without making changes. - -### API Approach - -The workflow uses a **delete-then-create** strategy for each rule: - -1. `DELETE /repos/{owner}/{repo}/branch_protections/{rule_name}` — remove existing rule (if any) -2. `POST /repos/{owner}/{repo}/branch_protections` — create fresh rule - -This avoids HTTP 422 errors from conflicting updates to existing rules. - ---- - -## Troubleshooting - -### HTTP 422 on Rule Creation - -**Symptom**: Rule fails to create with HTTP 422 - -**Common Causes**: -1. Username in whitelist doesn't exist as a Gitea user (e.g., bot accounts) -2. Rule name conflicts with an existing rule that wasn't deleted - -**Solution**: Check the error message in logs — it usually specifies which user or field is invalid - -### Rules Not Applying to Specific Repo - -**Symptom**: Repo not appearing in workflow output - -**Cause**: Repo is in the exclude list - -**Solution**: Check the `EXCLUDE` variable in the workflow and remove the repo if it should be governed - -### Protection Rules Reverted - -**Symptom**: Rules changed back to previous state after manual edit - -**Cause**: Weekly schedule re-applies standard rules every Monday - -**Solution**: Modify the workflow's rule definitions to make permanent changes — manual edits will be overwritten - ---- - -## Related Documentation - -- [Cascade Main → Dev](cascade-dev) -- [Dev Branch Tracking](dev-branch-tracking) -- [Bulk Repository Sync](bulk-repo-sync) -- [Workflow Architecture](workflow-architecture) - -## Changelog - -| Version | Date | Changes | -|---------|------|---------| +[![moko-platform](https://img.shields.io/badge/moko-platform-04.06.00-orange)](https://git.mokoconsulting.tech/MokoConsulting/moko-platform) + +# Branch Protection Setup Workflow + +**Status**: ✅ Active | **Version**: 01.00.00 | **Last Updated**: 2026-05-07 + +## Table of Contents + +- [Overview](#overview) +- [Protection Rules](#protection-rules) +- [Override Authority](#override-authority) +- [Workflow Triggers](#workflow-triggers) +- [Configuration](#configuration) +- [Excluded Repositories](#excluded-repositories) +- [Usage](#usage) +- [Troubleshooting](#troubleshooting) +- [Related Documentation](#related-documentation) + +--- + +## Overview + +The **Branch Protection Setup** workflow applies standardised branch protection rules to all governed repositories in the MokoConsulting organization. It runs from the **moko-platform** repository and uses the Gitea API to create or update protection rules across repos. + +### Purpose + +- **Consistency**: Uniform branch protection across all repositories +- **Drift Prevention**: Weekly scheduled runs enforce rules even if manually changed +- **Centralised Management**: Single workflow controls protection for the entire organization +- **Override Authority**: `jmiller` has full override capability on all branches + +### Key Features + +✅ **Idempotent**: Deletes and recreates rules to avoid update conflicts +✅ **Weekly Enforcement**: Scheduled every Monday at 02:00 UTC +✅ **Manual Dispatch**: Target specific repos or run against all +✅ **Dry Run Mode**: Preview changes without applying +✅ **Centralised**: Lives in moko-platform, applies to all governed repos + +--- + +## Protection Rules + +### Rule Summary + +| Branch | Push | Push Whitelist | Force Push | Force Push Whitelist | Block Rejected Reviews | Priority | +|--------|------|---------------|------------|---------------------|----------------------|----------| +| `main` | Whitelist | jmiller | Whitelist | jmiller | Yes | 1 | +| `dev` | Open | — | Whitelist | jmiller | No | 2 | +| `rc/*` | Open | — | Whitelist | jmiller | No | 3 | +| `beta/*` | Open | — | Whitelist | jmiller | No | 4 | +| `alpha/*` | Open | — | Whitelist | jmiller | No | 5 | + +### Rule Details + +#### `main` (Priority 1 — Strictest) + +- **Push**: Restricted to whitelist (`jmiller` only) +- **Force Push**: Restricted to whitelist (`jmiller` only) +- **Block on Rejected Reviews**: Yes — prevents merging PRs with rejected reviews +- **Dismiss Stale Approvals**: Yes — new commits invalidate previous approvals +- **Required Approvals**: 0 (solo developer workflow) + +#### `dev` (Priority 2) + +- **Push**: Open to all collaborators +- **Force Push**: Restricted to `jmiller` only +- **Block on Rejected Reviews**: No +- **Purpose**: Development integration branch — needs open push for cascade workflow and CI bots + +#### `rc/*`, `beta/*`, `alpha/*` (Priority 3-5) + +- **Push**: Open to all collaborators +- **Force Push**: Restricted to `jmiller` only +- **Block on Rejected Reviews**: No +- **Purpose**: Pre-release channels — CI workflows push version bumps and package builds directly + +--- + +## Override Authority + +**`jmiller`** has full override authority across all branches: + +- Can push directly to `main` (bypassing PR requirement) +- Can force-push to any branch when needed (emergency fixes, history cleanup) +- Is the only user in force-push whitelists on all branches + +This ensures the organization owner can always intervene in emergencies without being blocked by protection rules. + +--- + +## Workflow Triggers + +| Trigger | Condition | +|---------|-----------| +| `schedule` | Every Monday at 02:00 UTC (drift enforcement) | +| `workflow_dispatch` | Manual — supports `dry_run` and `repos` inputs | + +### Inputs + +| Input | Type | Default | Description | +|-------|------|---------|-------------| +| `dry_run` | boolean | `false` | Preview mode — logs what would change without applying | +| `repos` | string | `""` (all) | Comma-separated repo names to target (empty = all governed repos) | + +--- + +## Configuration + +### Environment Variables + +| Variable | Value | Description | +|----------|-------|-------------| +| `GITEA_URL` | `https://git.mokoconsulting.tech` | Gitea instance URL | +| `GITEA_ORG` | `MokoConsulting` | Organization name | + +### Secrets + +| Secret | Required | Description | +|--------|----------|-------------| +| `GA_TOKEN` | Yes | Gitea API token with admin/repo permissions | + +--- + +## Excluded Repositories + +The following repos are excluded from protection rule application: + +| Repository | Reason | +|-----------|--------| +| `gitea-org-config` | Platform infrastructure | +| `org-profile` | Platform infrastructure | +| `gitea-private` | Platform infrastructure | +| `gitea-server-setup` | Platform infrastructure | +| `moko-platform` | Standards repository | +| `moko-platform` | Standards repository | +| `MokoTesting` | Testing infrastructure | +| `moko-platform-Template-*` | Template repositories | +| `MokoDoliProjTemplate` | Template repository | + +--- + +## Usage + +### Apply to All Repos + +Trigger the workflow manually with default inputs (no dry run, all repos). + +### Apply to Specific Repos + +``` +repos: MokoOnyx,MokoJoomla,MokoJGDPC +``` + +### Preview Mode + +Set `dry_run: true` to see which rules would be applied without making changes. + +### API Approach + +The workflow uses a **delete-then-create** strategy for each rule: + +1. `DELETE /repos/{owner}/{repo}/branch_protections/{rule_name}` — remove existing rule (if any) +2. `POST /repos/{owner}/{repo}/branch_protections` — create fresh rule + +This avoids HTTP 422 errors from conflicting updates to existing rules. + +--- + +## Troubleshooting + +### HTTP 422 on Rule Creation + +**Symptom**: Rule fails to create with HTTP 422 + +**Common Causes**: +1. Username in whitelist doesn't exist as a Gitea user (e.g., bot accounts) +2. Rule name conflicts with an existing rule that wasn't deleted + +**Solution**: Check the error message in logs — it usually specifies which user or field is invalid + +### Rules Not Applying to Specific Repo + +**Symptom**: Repo not appearing in workflow output + +**Cause**: Repo is in the exclude list + +**Solution**: Check the `EXCLUDE` variable in the workflow and remove the repo if it should be governed + +### Protection Rules Reverted + +**Symptom**: Rules changed back to previous state after manual edit + +**Cause**: Weekly schedule re-applies standard rules every Monday + +**Solution**: Modify the workflow's rule definitions to make permanent changes — manual edits will be overwritten + +--- + +## Related Documentation + +- [Cascade Main → Dev](cascade-dev) +- [Dev Branch Tracking](dev-branch-tracking) +- [Bulk Repository Sync](bulk-repo-sync) +- [Workflow Architecture](workflow-architecture) + +## Changelog + +| Version | Date | Changes | +|---------|------|---------| | 01.00.00 | 2026-05-07 | Initial release — 5 branch rules across all governed repos | +--- + +*Repo: [moko-platform](https://git.mokoconsulting.tech/MokoConsulting/moko-platform) · [moko-platform wiki](https://git.mokoconsulting.tech/MokoConsulting/moko-platform/wiki/Home)* + +| Field | Value | +|---|---| +| Minimum Version | 04.07.00 | +| Platform | all | +| Applies To | All repositories | + +| Revision | Date | Author | Description | +|---|---|---|---| +| 1.0 | 2026-05-08 | Moko Consulting | Initial version | diff --git a/moko-platform/workflows-build-release.-.-.md b/moko-platform/workflows-build-release.-.-.md index ed4880d..118212b 100644 --- a/moko-platform/workflows-build-release.-.-.md +++ b/moko-platform/workflows-build-release.-.-.md @@ -74,3 +74,16 @@ Extracts release notes from CHANGELOG.md (section matching the version heading) | `deploy-dev.yml` | Deploys to dev server with version="development" | | `deploy-demo.yml` | Deploys to demo with real version | | `repository-cleanup.yml` | Deletes old version branches on schedule | +--- + +*Repo: [moko-platform](https://git.mokoconsulting.tech/MokoConsulting/moko-platform) · [moko-platform wiki](https://git.mokoconsulting.tech/MokoConsulting/moko-platform/wiki/Home)* + +| Field | Value | +|---|---| +| Minimum Version | 04.07.00 | +| Platform | all | +| Applies To | All repositories | + +| Revision | Date | Author | Description | +|---|---|---|---| +| 1.0 | 2026-05-08 | Moko Consulting | Initial version | diff --git a/moko-platform/workflows-cascade-dev.-.-.md b/moko-platform/workflows-cascade-dev.-.-.md index 00a629b..7fa1c32 100644 --- a/moko-platform/workflows-cascade-dev.-.-.md +++ b/moko-platform/workflows-cascade-dev.-.-.md @@ -1,210 +1,223 @@ ← [Home](Home) -[![moko-platform](https://img.shields.io/badge/moko-platform-05.00.00-orange)](https://git.mokoconsulting.tech/MokoConsulting/moko-platform) - -# Cascade Main → Dev Workflow - -**Status**: ✅ Active | **Version**: 02.00.00 | **Last Updated**: 2026-05-07 - -## Table of Contents - -- [Overview](#overview) -- [How It Works](#how-it-works) -- [Workflow Triggers](#workflow-triggers) -- [Configuration](#configuration) -- [Conflict Resolution](#conflict-resolution) -- [Skipping Cascade](#skipping-cascade) -- [Deployment](#deployment) -- [Troubleshooting](#troubleshooting) -- [Related Documentation](#related-documentation) - ---- - -## Overview - -The **Cascade Main → Dev** workflow automatically forward-merges `main` into all open branches (`dev`, `rc/*`, `beta/*`, `alpha/*`) after every push to `main`. This keeps all development and pre-release branches in sync with stable releases without manual intervention. - -### Purpose - -- **Sync**: Ensure all open branches (`dev`, `rc/*`, `beta/*`, `alpha/*`) always include the latest stable code from `main` -- **Automation**: Eliminate manual merge-forward after releases -- **Conflict Detection**: Surface merge conflicts early via auto-created PRs -- **Safety**: Never force-pushes or overwrites — creates PRs for manual resolution when needed - -### Key Features - -✅ **API-Only**: No repository checkout required — uses Gitea REST API exclusively -✅ **Idempotent**: Safe to run multiple times — detects existing PRs and skips duplicates -✅ **Conflict-Safe**: Creates a PR for manual resolution when auto-merge fails -✅ **Skip Support**: Opt out per-commit with `[skip cascade]` or `[skip ci]` -✅ **Deployed Org-Wide**: Active on all governed (non-platform/standards) repositories - ---- - -## How It Works - -``` -Push to main - ↓ -Discover target branches (dev, dev/*, rc/*, beta/*, alpha/*) - ↓ (skip if none found) -For each target branch: - ↓ - Compare main vs branch (commits ahead) - ↓ (skip if already in sync) - Create PR (main → branch) - ↓ (reuse existing if one is open) - Check mergeable - ├─ Clean → Auto-merge PR ✅ - └─ Conflicts → Leave PR open for manual resolution ⚠️ -``` - -### Step-by-Step - -1. **Branch Discovery**: Queries all branches via paginated API, filters to targets matching `dev`, `dev/*`, `rc/*`, `beta/*`, `alpha/*` -2. **Diff Check**: For each target, queries `GET /repos/{owner}/{repo}/compare/{branch}...main` — if `total_commits` is 0, the branch is already in sync -3. **PR Creation**: Creates a PR via `POST /repos/{owner}/{repo}/pulls` with `head: main`, `base: {branch}` -4. **Duplicate Prevention**: Before creating, checks for existing open PRs with the same head/base -5. **Auto-Merge**: If `mergeable: true`, merges via `POST /repos/{owner}/{repo}/pulls/{index}/merge` with merge style -6. **Conflict Handling**: If `mergeable: false`, the PR stays open with a clear description for manual resolution - ---- - -## Workflow Triggers - -| Trigger | Condition | -|---------|-----------| -| `push` to `main` | Every push (PR merges, bot commits, direct pushes) | -| `workflow_dispatch` | Manual trigger from Gitea Actions UI | - -### Automatic Skipping - -The workflow skips execution when: -- The commit message contains `[skip ci]` -- The commit message contains `[skip cascade]` - ---- - -## Configuration - -### Environment Variables - -| Variable | Default | Description | -|----------|---------|-------------| -| `GITEA_URL` | `https://git.mokoconsulting.tech` | Gitea instance URL | -| `GITEA_ORG` | `github.repository_owner` | Organization name | -| `GITEA_REPO` | `github.event.repository.name` | Repository name | - -### Secrets - -| Secret | Required | Description | -|--------|----------|-------------| -| `GA_TOKEN` | Yes | Gitea API token with repo write + PR permissions | - -### Runner - -Runs on `ubuntu-latest` — no special runner requirements. - ---- - -## Conflict Resolution - -When the auto-merge detects conflicts: - -1. The workflow creates (or reuses) a PR titled `chore: cascade main → {branch} ({sha}) [skip ci]` -2. The PR body explains the conflict and links to the workflow -3. The workflow exits successfully (not a failure — conflicts are expected) -4. A developer must: - - Check out the PR locally - - Resolve conflicts - - Push the resolution - - Merge the PR - -### Common Conflict Sources - -- **Version files**: `README.md` VERSION header, `updates.xml` (dev has different version than main) -- **Changelog**: Both branches modified `CHANGELOG.md` -- **CI configs**: Workflow files modified independently on both branches - ---- - -## Skipping Cascade - -### Per-Commit - -Add `[skip cascade]` to the commit message: - -```bash -git commit -m "chore: version bump [skip cascade]" -``` - -### Per-Push - -The `[skip ci]` tag also prevents cascade (since the workflow checks both). - ---- - -## Deployment - -The workflow file `.gitea/workflows/cascade-dev.yml` is deployed to all governed repositories (non-platform, non-standards, non-template repos). - -### Excluded Repositories - -- `gitea-org-config`, `org-profile`, `gitea-private`, `gitea-server-setup` — Platform/infra -- `moko-platform`, `moko-platform`, `MokoTesting` — Standards repos -- `moko-platform-Template-*`, `MokoDoliProjTemplate` — Template repos - -### Adding to a New Repository - -The cascade workflow is automatically deployed by the bulk sync process. To manually add: - -1. Copy `.gitea/workflows/cascade-dev.yml` from any governed repo -2. Ensure the repo has at least one target branch (`dev`, `rc/*`, `beta/*`, or `alpha/*`) -3. Ensure `GA_TOKEN` secret is configured - ---- - -## Troubleshooting - -### Cascade Not Triggering - -**Symptom**: Push to main but no cascade run - -**Causes**: -1. Commit message contains `[skip ci]` or `[skip cascade]` -2. Workflow file missing from repo -3. `GA_TOKEN` secret not configured - -**Solution**: Check Actions tab for skipped runs; verify workflow file exists on `main` - -### Cascade Creates PR But Doesn't Merge - -**Symptom**: PR created but left open - -**Cause**: Merge conflicts between `main` and the target branch - -**Solution**: Resolve conflicts locally and merge the PR manually - -### "No cascade target branches found" Message - -**Symptom**: Workflow logs show "No cascade target branches found" - -**Cause**: Repository doesn't have any target branches (`dev`, `rc/*`, `beta/*`, `alpha/*`) - -**Solution**: Create a target branch from main: `git checkout -b dev main && git push origin dev` - ---- - -## Related Documentation - -- [Branch Protection Setup](branch-protection) -- [Dev Branch Tracking](dev-branch-tracking) -- [Workflow Architecture](workflow-architecture) -- [Bulk Repository Sync](bulk-repo-sync) - -## Changelog - -| Version | Date | Changes | -|---------|------|---------| -| 01.00.00 | 2026-05-07 | Initial release — PR-based merge with conflict detection | +[![moko-platform](https://img.shields.io/badge/moko-platform-04.06.00-orange)](https://git.mokoconsulting.tech/MokoConsulting/moko-platform) + +# Cascade Main → Dev Workflow + +**Status**: ✅ Active | **Version**: 02.00.00 | **Last Updated**: 2026-05-07 + +## Table of Contents + +- [Overview](#overview) +- [How It Works](#how-it-works) +- [Workflow Triggers](#workflow-triggers) +- [Configuration](#configuration) +- [Conflict Resolution](#conflict-resolution) +- [Skipping Cascade](#skipping-cascade) +- [Deployment](#deployment) +- [Troubleshooting](#troubleshooting) +- [Related Documentation](#related-documentation) + +--- + +## Overview + +The **Cascade Main → Dev** workflow automatically forward-merges `main` into all open branches (`dev`, `rc/*`, `beta/*`, `alpha/*`) after every push to `main`. This keeps all development and pre-release branches in sync with stable releases without manual intervention. + +### Purpose + +- **Sync**: Ensure all open branches (`dev`, `rc/*`, `beta/*`, `alpha/*`) always include the latest stable code from `main` +- **Automation**: Eliminate manual merge-forward after releases +- **Conflict Detection**: Surface merge conflicts early via auto-created PRs +- **Safety**: Never force-pushes or overwrites — creates PRs for manual resolution when needed + +### Key Features + +✅ **API-Only**: No repository checkout required — uses Gitea REST API exclusively +✅ **Idempotent**: Safe to run multiple times — detects existing PRs and skips duplicates +✅ **Conflict-Safe**: Creates a PR for manual resolution when auto-merge fails +✅ **Skip Support**: Opt out per-commit with `[skip cascade]` or `[skip ci]` +✅ **Deployed Org-Wide**: Active on all governed (non-platform/standards) repositories + +--- + +## How It Works + +``` +Push to main + ↓ +Discover target branches (dev, dev/*, rc/*, beta/*, alpha/*) + ↓ (skip if none found) +For each target branch: + ↓ + Compare main vs branch (commits ahead) + ↓ (skip if already in sync) + Create PR (main → branch) + ↓ (reuse existing if one is open) + Check mergeable + ├─ Clean → Auto-merge PR ✅ + └─ Conflicts → Leave PR open for manual resolution ⚠️ +``` + +### Step-by-Step + +1. **Branch Discovery**: Queries all branches via paginated API, filters to targets matching `dev`, `dev/*`, `rc/*`, `beta/*`, `alpha/*` +2. **Diff Check**: For each target, queries `GET /repos/{owner}/{repo}/compare/{branch}...main` — if `total_commits` is 0, the branch is already in sync +3. **PR Creation**: Creates a PR via `POST /repos/{owner}/{repo}/pulls` with `head: main`, `base: {branch}` +4. **Duplicate Prevention**: Before creating, checks for existing open PRs with the same head/base +5. **Auto-Merge**: If `mergeable: true`, merges via `POST /repos/{owner}/{repo}/pulls/{index}/merge` with merge style +6. **Conflict Handling**: If `mergeable: false`, the PR stays open with a clear description for manual resolution + +--- + +## Workflow Triggers + +| Trigger | Condition | +|---------|-----------| +| `push` to `main` | Every push (PR merges, bot commits, direct pushes) | +| `workflow_dispatch` | Manual trigger from Gitea Actions UI | + +### Automatic Skipping + +The workflow skips execution when: +- The commit message contains `[skip ci]` +- The commit message contains `[skip cascade]` + +--- + +## Configuration + +### Environment Variables + +| Variable | Default | Description | +|----------|---------|-------------| +| `GITEA_URL` | `https://git.mokoconsulting.tech` | Gitea instance URL | +| `GITEA_ORG` | `github.repository_owner` | Organization name | +| `GITEA_REPO` | `github.event.repository.name` | Repository name | + +### Secrets + +| Secret | Required | Description | +|--------|----------|-------------| +| `GA_TOKEN` | Yes | Gitea API token with repo write + PR permissions | + +### Runner + +Runs on `ubuntu-latest` — no special runner requirements. + +--- + +## Conflict Resolution + +When the auto-merge detects conflicts: + +1. The workflow creates (or reuses) a PR titled `chore: cascade main → {branch} ({sha}) [skip ci]` +2. The PR body explains the conflict and links to the workflow +3. The workflow exits successfully (not a failure — conflicts are expected) +4. A developer must: + - Check out the PR locally + - Resolve conflicts + - Push the resolution + - Merge the PR + +### Common Conflict Sources + +- **Version files**: `README.md` VERSION header, `updates.xml` (dev has different version than main) +- **Changelog**: Both branches modified `CHANGELOG.md` +- **CI configs**: Workflow files modified independently on both branches + +--- + +## Skipping Cascade + +### Per-Commit + +Add `[skip cascade]` to the commit message: + +```bash +git commit -m "chore: version bump [skip cascade]" +``` + +### Per-Push + +The `[skip ci]` tag also prevents cascade (since the workflow checks both). + +--- + +## Deployment + +The workflow file `.gitea/workflows/cascade-dev.yml` is deployed to all governed repositories (non-platform, non-standards, non-template repos). + +### Excluded Repositories + +- `gitea-org-config`, `org-profile`, `gitea-private`, `gitea-server-setup` — Platform/infra +- `moko-platform`, `moko-platform`, `MokoTesting` — Standards repos +- `moko-platform-Template-*`, `MokoDoliProjTemplate` — Template repos + +### Adding to a New Repository + +The cascade workflow is automatically deployed by the bulk sync process. To manually add: + +1. Copy `.gitea/workflows/cascade-dev.yml` from any governed repo +2. Ensure the repo has at least one target branch (`dev`, `rc/*`, `beta/*`, or `alpha/*`) +3. Ensure `GA_TOKEN` secret is configured + +--- + +## Troubleshooting + +### Cascade Not Triggering + +**Symptom**: Push to main but no cascade run + +**Causes**: +1. Commit message contains `[skip ci]` or `[skip cascade]` +2. Workflow file missing from repo +3. `GA_TOKEN` secret not configured + +**Solution**: Check Actions tab for skipped runs; verify workflow file exists on `main` + +### Cascade Creates PR But Doesn't Merge + +**Symptom**: PR created but left open + +**Cause**: Merge conflicts between `main` and the target branch + +**Solution**: Resolve conflicts locally and merge the PR manually + +### "No cascade target branches found" Message + +**Symptom**: Workflow logs show "No cascade target branches found" + +**Cause**: Repository doesn't have any target branches (`dev`, `rc/*`, `beta/*`, `alpha/*`) + +**Solution**: Create a target branch from main: `git checkout -b dev main && git push origin dev` + +--- + +## Related Documentation + +- [Branch Protection Setup](branch-protection) +- [Dev Branch Tracking](dev-branch-tracking) +- [Workflow Architecture](workflow-architecture) +- [Bulk Repository Sync](bulk-repo-sync) + +## Changelog + +| Version | Date | Changes | +|---------|------|---------| +| 01.00.00 | 2026-05-07 | Initial release — PR-based merge with conflict detection | | 02.00.00 | 2026-05-07 | Cascade to all open branches (dev, rc/*, beta/*, alpha/*), not just dev | +--- + +*Repo: [moko-platform](https://git.mokoconsulting.tech/MokoConsulting/moko-platform) · [moko-platform wiki](https://git.mokoconsulting.tech/MokoConsulting/moko-platform/wiki/Home)* + +| Field | Value | +|---|---| +| Minimum Version | 04.07.00 | +| Platform | all | +| Applies To | All repositories | + +| Revision | Date | Author | Description | +|---|---|---|---| +| 1.0 | 2026-05-08 | Moko Consulting | Initial version | diff --git a/moko-platform/workflows-changelog-management.-.-.md b/moko-platform/workflows-changelog-management.-.-.md index 2fcf40b..5fbf03e 100644 --- a/moko-platform/workflows-changelog-management.-.-.md +++ b/moko-platform/workflows-changelog-management.-.-.md @@ -1,324 +1,337 @@ ← [Home](Home) -[![moko-platform](https://img.shields.io/badge/moko-platform-05.00.00-orange)](https://git.mokoconsulting.tech/MokoConsulting/moko-platform) - -# Changelog Management System - -This document describes the changelog management system for moko-platform, including scripts and workflows for maintaining CHANGELOG.md according to [Keep a Changelog](https://keepachangelog.com/) format. - -## Overview - -The changelog management system consists of: - -1. **Scripts**: Python scripts for updating and releasing versions -2. **Workflows**: Gitea Actions for automated changelog management -3. **Format**: Follows Keep a Changelog with Semantic Versioning - -## Scripts - -### update_changelog.py - -Updates CHANGELOG.md by adding entries to the UNRELEASED section. - -**Usage**: -```bash -# Add a simple entry -python3 api/maintenance/update_changelog.py --category Added --entry "New feature X" - -# Add an entry with subcategory -python3 api/maintenance/update_changelog.py --category Changed --entry "Updated API" --subcategory "API" - -# Display current UNRELEASED section -python3 api/maintenance/update_changelog.py --show -``` - -**Categories**: Added, Changed, Deprecated, Removed, Fixed, Security - -**Features**: -- Automatically creates category sections if they don't exist -- Maintains proper formatting and indentation -- Supports subcategories for better organization -- Validates category names - -### release_version.py - -Releases a version by moving UNRELEASED items to a versioned section, updating VERSION headers in files, and optionally creating a GitHub release. - -**Usage**: -```bash -# Release version (updates CHANGELOG only) -python3 api/maintenance/release_version.py --version 05.01.00 - -# Release with custom date -python3 api/maintenance/release_version.py --version 05.01.00 --date 2026-01-15 - -# Release and update VERSION in all files -python3 api/maintenance/release_version.py --version 05.01.00 --update-files - -# Release, update files, and create GitHub release -python3 api/maintenance/release_version.py --version 05.01.00 --update-files --create-release - -# Dry run to preview changes -python3 api/maintenance/release_version.py --version 05.01.00 --update-files --create-release --dry-run -``` - -**Features**: -- Validates version format (XX.YY.ZZ) -- Moves UNRELEASED content to new version section -- Updates VERSION header in all repository files -- Creates GitHub releases with extracted notes -- Supports dry-run mode for testing - -## Workflows - -### Update Changelog Workflow - -**File**: `.gitea/workflows/changelog_update.yml` - -**Trigger**: Manual workflow dispatch - -**Purpose**: Add entries to CHANGELOG.md UNRELEASED section via Gitea Actions UI - -**Inputs**: -- `category`: Changelog category (Added/Changed/Deprecated/Removed/Fixed/Security) -- `entry`: Entry text -- `subcategory`: Optional subcategory/subheading - -**Process**: -1. Runs update_changelog.py script -2. Creates a Pull Request with changes -3. Labels PR with `documentation` and `automated` - -**Usage**: -1. Go to Actions → Update Changelog -2. Click "Run workflow" -3. Fill in the form -4. Review and merge the created PR - -### Version Release Workflow - -**File**: `.gitea/workflows/version_release.yml` - -**Trigger**: Manual workflow dispatch - -**Purpose**: Release a new version by moving UNRELEASED items, updating files, and creating GitHub release - -**Inputs**: -- `version`: Version number in XX.YY.ZZ format -- `date`: Optional release date (defaults to today) -- `update_files`: Whether to update VERSION in all files -- `create_release`: Whether to create GitHub release - -**Process**: -1. Validates version format -2. Releases version in CHANGELOG.md -3. Updates VERSION headers in all files (if enabled) -4. Commits changes -5. Creates Pull Request for review -6. Creates GitHub release after PR merge (if enabled) - -**Usage**: -1. Go to Actions → Release Version -2. Click "Run workflow" -3. Enter version number (e.g., 05.01.00) -4. Select options (update files, create release) -5. Review and merge the created PR -6. GitHub release is created automatically - -## Changelog Format - -### Structure - -```markdown -# Changelog - -## [UNRELEASED] - -## [05.01.00] - 2026-01-15 -### Added -- New feature description - -### Changed -- Change description - -### Security -- Security improvement - -## [05.00.00] - 2026-01-04 -... -``` - -### Categories - -- **Added**: New features -- **Changed**: Changes in existing functionality -- **Deprecated**: Soon-to-be removed features -- **Removed**: Removed features -- **Fixed**: Bug fixes -- **Security**: Security improvements - -### Best Practices - -1. **Be Specific**: Describe what changed and why -2. **User-Focused**: Write from user's perspective -3. **Group Related**: Use subcategories for related changes -4. **Link Issues**: Reference issue/PR numbers when relevant -5. **Keep Updated**: Add entries as changes are made - -## Version Format - -Versions follow the format: **XX.YY.ZZ** - -- **XX**: Major version (breaking changes) -- **YY**: Minor version (new features, backward compatible) -- **ZZ**: Patch version (bug fixes) - -Examples: `05.00.00`, `05.01.00`, `05.01.01` - -## Integration with Development Workflow - -### During Development - -1. Make code changes -2. Add changelog entry using script or workflow: - ```bash - python3 api/maintenance/update_changelog.py --category Added --entry "Feature description" - ``` -3. Commit both code and changelog changes - -### For Releases - -1. Ensure all changes are in UNRELEASED section -2. Run version release workflow: - - Actions → Release Version - - Enter version number - - Enable "Update files" and "Create release" -3. Review the created PR -4. Merge PR to complete release -5. GitHub release is created automatically - -### Manual Release (Alternative) - -```bash -# 1. Release version -python3 api/maintenance/release_version.py --version 05.01.00 --update-files - -# 2. Commit changes -git add . -git commit -m "release: version 05.01.00" - -# 3. Create GitHub release -python3 api/maintenance/release_version.py --version 05.01.00 --create-release - -# 4. Push changes -git push origin main -``` - -## File VERSION Headers - -All files with version headers are automatically updated during release: - -```markdown -VERSION: 05.00.00 -``` - -Supported file types: -- Markdown (`.md`) -- Python (`.py`) -- YAML (`.yml`, `.yaml`) -- Text (`.txt`) - -## GitHub Release Creation - -When `--create-release` is used, the script: - -1. Extracts release notes from CHANGELOG.md for the version -2. Creates a Git tag (e.g., `v05.01.00`) -3. Creates GitHub release with: - - Tag name: `v{version}` - - Title: `Release {version}` - - Notes: Extracted from CHANGELOG.md - -Requires `gh` CLI to be installed and authenticated. - -## Troubleshooting - -### UNRELEASED Section Not Found - -Ensure CHANGELOG.md has an `## [UNRELEASED]` heading. - -### Version Format Error - -Use XX.YY.ZZ format (e.g., `05.01.00`, not `5.1.0`). - -### GitHub Release Failed - -- Ensure `gh` CLI is installed: `gh --version` -- Authenticate: `gh auth login` -- Check repository permissions - -### File Update Issues - -- Ensure files have VERSION headers in correct format -- Check file permissions -- Review dry-run output first - -## Examples - -### Example 1: Add New Feature - -```bash -# Add to UNRELEASED -python3 api/maintenance/update_changelog.py \ - --category Added \ - --entry "Support for custom themes" \ - --subcategory "UI" - -# View changes -python3 api/maintenance/update_changelog.py --show -``` - -### Example 2: Release Minor Version - -```bash -# Release 05.01.00 -python3 api/maintenance/release_version.py \ - --version 05.01.00 \ - --update-files \ - --create-release -``` - -### Example 3: Security Update - -```bash -# Add security entry -python3 api/maintenance/update_changelog.py \ - --category Security \ - --entry "Fix XSS vulnerability in user input" - -# Release patch version -python3 api/maintenance/release_version.py \ - --version 05.00.01 \ - --update-files \ - --create-release -``` - -## References - -- [Keep a Changelog](https://keepachangelog.com/) -- [Semantic Versioning](https://semver.org/) -- [GitHub CLI Documentation](https://cli.github.com/manual/) - +[![moko-platform](https://img.shields.io/badge/moko-platform-04.06.00-orange)](https://git.mokoconsulting.tech/MokoConsulting/moko-platform) + +# Changelog Management System + +This document describes the changelog management system for moko-platform, including scripts and workflows for maintaining CHANGELOG.md according to [Keep a Changelog](https://keepachangelog.com/) format. + +## Overview + +The changelog management system consists of: + +1. **Scripts**: Python scripts for updating and releasing versions +2. **Workflows**: Gitea Actions for automated changelog management +3. **Format**: Follows Keep a Changelog with Semantic Versioning + +## Scripts + +### update_changelog.py + +Updates CHANGELOG.md by adding entries to the UNRELEASED section. + +**Usage**: +```bash +# Add a simple entry +python3 api/maintenance/update_changelog.py --category Added --entry "New feature X" + +# Add an entry with subcategory +python3 api/maintenance/update_changelog.py --category Changed --entry "Updated API" --subcategory "API" + +# Display current UNRELEASED section +python3 api/maintenance/update_changelog.py --show +``` + +**Categories**: Added, Changed, Deprecated, Removed, Fixed, Security + +**Features**: +- Automatically creates category sections if they don't exist +- Maintains proper formatting and indentation +- Supports subcategories for better organization +- Validates category names + +### release_version.py + +Releases a version by moving UNRELEASED items to a versioned section, updating VERSION headers in files, and optionally creating a GitHub release. + +**Usage**: +```bash +# Release version (updates CHANGELOG only) +python3 api/maintenance/release_version.py --version 05.01.00 + +# Release with custom date +python3 api/maintenance/release_version.py --version 05.01.00 --date 2026-01-15 + +# Release and update VERSION in all files +python3 api/maintenance/release_version.py --version 05.01.00 --update-files + +# Release, update files, and create GitHub release +python3 api/maintenance/release_version.py --version 05.01.00 --update-files --create-release + +# Dry run to preview changes +python3 api/maintenance/release_version.py --version 05.01.00 --update-files --create-release --dry-run +``` + +**Features**: +- Validates version format (XX.YY.ZZ) +- Moves UNRELEASED content to new version section +- Updates VERSION header in all repository files +- Creates GitHub releases with extracted notes +- Supports dry-run mode for testing + +## Workflows + +### Update Changelog Workflow + +**File**: `.gitea/workflows/changelog_update.yml` + +**Trigger**: Manual workflow dispatch + +**Purpose**: Add entries to CHANGELOG.md UNRELEASED section via Gitea Actions UI + +**Inputs**: +- `category`: Changelog category (Added/Changed/Deprecated/Removed/Fixed/Security) +- `entry`: Entry text +- `subcategory`: Optional subcategory/subheading + +**Process**: +1. Runs update_changelog.py script +2. Creates a Pull Request with changes +3. Labels PR with `documentation` and `automated` + +**Usage**: +1. Go to Actions → Update Changelog +2. Click "Run workflow" +3. Fill in the form +4. Review and merge the created PR + +### Version Release Workflow + +**File**: `.gitea/workflows/version_release.yml` + +**Trigger**: Manual workflow dispatch + +**Purpose**: Release a new version by moving UNRELEASED items, updating files, and creating GitHub release + +**Inputs**: +- `version`: Version number in XX.YY.ZZ format +- `date`: Optional release date (defaults to today) +- `update_files`: Whether to update VERSION in all files +- `create_release`: Whether to create GitHub release + +**Process**: +1. Validates version format +2. Releases version in CHANGELOG.md +3. Updates VERSION headers in all files (if enabled) +4. Commits changes +5. Creates Pull Request for review +6. Creates GitHub release after PR merge (if enabled) + +**Usage**: +1. Go to Actions → Release Version +2. Click "Run workflow" +3. Enter version number (e.g., 05.01.00) +4. Select options (update files, create release) +5. Review and merge the created PR +6. GitHub release is created automatically + +## Changelog Format + +### Structure + +```markdown +# Changelog + +## [UNRELEASED] + +## [05.01.00] - 2026-01-15 +### Added +- New feature description + +### Changed +- Change description + +### Security +- Security improvement + +## [05.00.00] - 2026-01-04 +... +``` + +### Categories + +- **Added**: New features +- **Changed**: Changes in existing functionality +- **Deprecated**: Soon-to-be removed features +- **Removed**: Removed features +- **Fixed**: Bug fixes +- **Security**: Security improvements + +### Best Practices + +1. **Be Specific**: Describe what changed and why +2. **User-Focused**: Write from user's perspective +3. **Group Related**: Use subcategories for related changes +4. **Link Issues**: Reference issue/PR numbers when relevant +5. **Keep Updated**: Add entries as changes are made + +## Version Format + +Versions follow the format: **XX.YY.ZZ** + +- **XX**: Major version (breaking changes) +- **YY**: Minor version (new features, backward compatible) +- **ZZ**: Patch version (bug fixes) + +Examples: `05.00.00`, `05.01.00`, `05.01.01` + +## Integration with Development Workflow + +### During Development + +1. Make code changes +2. Add changelog entry using script or workflow: + ```bash + python3 api/maintenance/update_changelog.py --category Added --entry "Feature description" + ``` +3. Commit both code and changelog changes + +### For Releases + +1. Ensure all changes are in UNRELEASED section +2. Run version release workflow: + - Actions → Release Version + - Enter version number + - Enable "Update files" and "Create release" +3. Review the created PR +4. Merge PR to complete release +5. GitHub release is created automatically + +### Manual Release (Alternative) + +```bash +# 1. Release version +python3 api/maintenance/release_version.py --version 05.01.00 --update-files + +# 2. Commit changes +git add . +git commit -m "release: version 05.01.00" + +# 3. Create GitHub release +python3 api/maintenance/release_version.py --version 05.01.00 --create-release + +# 4. Push changes +git push origin main +``` + +## File VERSION Headers + +All files with version headers are automatically updated during release: + +```markdown +VERSION: 04.06.00 +``` + +Supported file types: +- Markdown (`.md`) +- Python (`.py`) +- YAML (`.yml`, `.yaml`) +- Text (`.txt`) + +## GitHub Release Creation + +When `--create-release` is used, the script: + +1. Extracts release notes from CHANGELOG.md for the version +2. Creates a Git tag (e.g., `v05.01.00`) +3. Creates GitHub release with: + - Tag name: `v{version}` + - Title: `Release {version}` + - Notes: Extracted from CHANGELOG.md + +Requires `gh` CLI to be installed and authenticated. + +## Troubleshooting + +### UNRELEASED Section Not Found + +Ensure CHANGELOG.md has an `## [UNRELEASED]` heading. + +### Version Format Error + +Use XX.YY.ZZ format (e.g., `05.01.00`, not `5.1.0`). + +### GitHub Release Failed + +- Ensure `gh` CLI is installed: `gh --version` +- Authenticate: `gh auth login` +- Check repository permissions + +### File Update Issues + +- Ensure files have VERSION headers in correct format +- Check file permissions +- Review dry-run output first + +## Examples + +### Example 1: Add New Feature + +```bash +# Add to UNRELEASED +python3 api/maintenance/update_changelog.py \ + --category Added \ + --entry "Support for custom themes" \ + --subcategory "UI" + +# View changes +python3 api/maintenance/update_changelog.py --show +``` + +### Example 2: Release Minor Version + +```bash +# Release 05.01.00 +python3 api/maintenance/release_version.py \ + --version 05.01.00 \ + --update-files \ + --create-release +``` + +### Example 3: Security Update + +```bash +# Add security entry +python3 api/maintenance/update_changelog.py \ + --category Security \ + --entry "Fix XSS vulnerability in user input" + +# Release patch version +python3 api/maintenance/release_version.py \ + --version 05.00.01 \ + --update-files \ + --create-release +``` + +## References + +- [Keep a Changelog](https://keepachangelog.com/) +- [Semantic Versioning](https://semver.org/) +- [GitHub CLI Documentation](https://cli.github.com/manual/) + +--- + +## Metadata + +**Document Version**: 05.00.00 +**Last Updated**: 2026-01-04 +**Status**: Active + +## Revision History + +| Version | Date | Description | +|---------|------|-------------| +| 05.00.00 | 2026-01-04 | Initial changelog management system documentation | --- -## Metadata +*Repo: [moko-platform](https://git.mokoconsulting.tech/MokoConsulting/moko-platform) · [moko-platform wiki](https://git.mokoconsulting.tech/MokoConsulting/moko-platform/wiki/Home)* -**Document Version**: 05.00.00 -**Last Updated**: 2026-01-04 -**Status**: Active +| Field | Value | +|---|---| +| Minimum Version | 04.07.00 | +| Platform | all | +| Applies To | All repositories | -## Revision History - -| Version | Date | Description | -|---------|------|-------------| -| 05.00.00 | 2026-01-04 | Initial changelog management system documentation | +| Revision | Date | Author | Description | +|---|---|---|---| +| 1.0 | 2026-05-08 | Moko Consulting | Initial version | diff --git a/moko-platform/workflows-demo-deployment.-.-.md b/moko-platform/workflows-demo-deployment.-.-.md index 3965e26..c5004d4 100644 --- a/moko-platform/workflows-demo-deployment.-.-.md +++ b/moko-platform/workflows-demo-deployment.-.-.md @@ -1,6 +1,6 @@ ← [Home](Home) -[![moko-platform](https://img.shields.io/badge/moko-platform-05.00.00-orange)](https://git.mokoconsulting.tech/MokoConsulting/moko-platform) +[![moko-platform](https://img.shields.io/badge/moko-platform-04.06.00-orange)](https://git.mokoconsulting.tech/MokoConsulting/moko-platform) # Demo Server Deployment @@ -59,3 +59,16 @@ At least one of `DEMO_FTP_KEY` or `DEMO_FTP_PASSWORD` must be set. - [.ftpignore Reference](deployment-ftpignore) > **Note:** `deploy-rs.yml` has been retired. RS deployment is handled via the release pipeline only. +--- + +*Repo: [moko-platform](https://git.mokoconsulting.tech/MokoConsulting/moko-platform) · [moko-platform wiki](https://git.mokoconsulting.tech/MokoConsulting/moko-platform/wiki/Home)* + +| Field | Value | +|---|---| +| Minimum Version | 04.07.00 | +| Platform | all | +| Applies To | All repositories | + +| Revision | Date | Author | Description | +|---|---|---|---| +| 1.0 | 2026-05-08 | Moko Consulting | Initial version | diff --git a/moko-platform/workflows-dev-branch-tracking.-.-.md b/moko-platform/workflows-dev-branch-tracking.-.-.md index e4f9cf6..5a517c5 100644 --- a/moko-platform/workflows-dev-branch-tracking.-.-.md +++ b/moko-platform/workflows-dev-branch-tracking.-.-.md @@ -1,6 +1,6 @@ ← [Home](Home) -[![moko-platform](https://img.shields.io/badge/moko-platform-05.00.00-orange)](https://git.mokoconsulting.tech/MokoConsulting/moko-platform) +[![moko-platform](https://img.shields.io/badge/moko-platform-04.06.00-orange)](https://git.mokoconsulting.tech/MokoConsulting/moko-platform) # Dev Branch Tracking and Issue Coordination @@ -376,3 +376,16 @@ To modify patterns, edit `.gitea/workflows/enterprise-issue-manager.yml` line 14 |---------|------|---------| | 02.00.00 | 2026-04-07 | Rewrite: dev branches use manual workflow_dispatch, RC branches auto-create issues + draft release. Updated sub-issue counts (7 for dev, 5 for RC) | | 01.00.00 | 2026-02-06 | Initial documentation of dev branch tracking system | +--- + +*Repo: [moko-platform](https://git.mokoconsulting.tech/MokoConsulting/moko-platform) · [moko-platform wiki](https://git.mokoconsulting.tech/MokoConsulting/moko-platform/wiki/Home)* + +| Field | Value | +|---|---| +| Minimum Version | 04.07.00 | +| Platform | all | +| Applies To | All repositories | + +| Revision | Date | Author | Description | +|---|---|---|---| +| 1.0 | 2026-05-08 | Moko Consulting | Initial version | diff --git a/moko-platform/workflows-dev-deployment.-.-.md b/moko-platform/workflows-dev-deployment.-.-.md index c160d46..76dec6c 100644 --- a/moko-platform/workflows-dev-deployment.-.-.md +++ b/moko-platform/workflows-dev-deployment.-.-.md @@ -1,6 +1,6 @@ ← [Home](Home) -[![moko-platform](https://img.shields.io/badge/moko-platform-05.00.00-orange)](https://git.mokoconsulting.tech/MokoConsulting/moko-platform) +[![moko-platform](https://img.shields.io/badge/moko-platform-04.06.00-orange)](https://git.mokoconsulting.tech/MokoConsulting/moko-platform) # Development Server Deployment @@ -252,7 +252,7 @@ Expected behaviour for repos without a `src/` directory. No files are uploaded; | Owner | Moko Consulting | | Repo | https://git.mokoconsulting.tech/MokoConsulting/moko-platform | | Path | /docs/workflows/dev-deployment.md | -| Version | 05.00.00 | +| Version | 04.06.00 | | Status | Active | | Last Reviewed | 2026-04-07 | | Reviewed By | Documentation Team | @@ -264,3 +264,16 @@ Expected behaviour for repos without a `src/` directory. No files are uploaded; | 2026-03-12 | Moko Consulting | Rewrote for SFTP-only workflow; added auth fallback, port resolution, health check docs | | 2026-01-28 | Moko Consulting | Standardized metadata and revision history | | 2026-01-17 | Moko Consulting | Initial dev deployment workflow documentation | +--- + +*Repo: [moko-platform](https://git.mokoconsulting.tech/MokoConsulting/moko-platform) · [moko-platform wiki](https://git.mokoconsulting.tech/MokoConsulting/moko-platform/wiki/Home)* + +| Field | Value | +|---|---| +| Minimum Version | 04.07.00 | +| Platform | all | +| Applies To | All repositories | + +| Revision | Date | Author | Description | +|---|---|---|---| +| 1.0 | 2026-05-08 | Moko Consulting | Initial version | diff --git a/moko-platform/workflows-index.-.-.md b/moko-platform/workflows-index.-.-.md index f43173d..c8d87e3 100644 --- a/moko-platform/workflows-index.-.-.md +++ b/moko-platform/workflows-index.-.-.md @@ -1,77 +1,90 @@ ← [Home](Home) -[![moko-platform](https://img.shields.io/badge/moko-platform-05.00.00-orange)](https://git.mokoconsulting.tech/MokoConsulting/moko-platform) +[![moko-platform](https://img.shields.io/badge/moko-platform-04.06.00-orange)](https://git.mokoconsulting.tech/MokoConsulting/moko-platform) + +# workflows + +## Purpose + +Documentation for all Gitea Actions workflows used across governed repositories. + +## Deployment Workflows + +### Dolibarr + Generic (automatic FTP deploy) + +- [Dev Deployment](dev-deployment) — deploy to dev FTP on push to `dev/**`, `alpha/**`, `beta/**`, or `rc/**` +- [Demo Deployment](demo-deployment) — deploy to demo FTP on push to `main` + +> **Note:** `deploy-rs.yml` is **retired**. RS deployment is handled via the release pipeline only. See [RS Deployment (deprecated)](rs-deployment). + +### Joomla (no automatic FTP deploy) + +Joomla repos use GitHub Release ZIPs via `auto-release.yml` + `updates.xml`. No automatic FTP deploy. + +- [Deploy Manual](deploy-manual) — manual workflow_dispatch FTP deploy for Joomla dev testing + +## Release & Version Workflows + +- [Auto Release](auto-release) — platform-specific GitHub Release on push to main (generic, Joomla, Dolibarr) +- [Build Release](build-release) — build release artifacts +- [Release System](release-system) — end-to-end release lifecycle (dev → rc → main) +- [Changelog Management](changelog-management) — automated changelog generation +- [Changelog Validation](changelog-validation) — validates CHANGELOG.md format on PR + +## Client Repositories + +- [Client Repo Standards](client-repos) — naming, privacy, structure, deployment for client-* repos + +## CI & Compliance Workflows + +- [CI Joomla](ci-joomla) — Joomla-specific CI checks (manifest validation, language files, XML lint) +- [CI Dolibarr](ci-dolibarr) — Dolibarr-specific CI checks (module descriptor, PHP lint) +- [Standards Compliance](standards-compliance) — enterprise standards validation +- [Repo Health](repo-health) — platform-aware repository health checks +- [Shared Workflows](shared-workflows) — reusable workflow templates +- [Reusable Workflows](reusable-workflows) — reusable workflow reference +- [Workflow Architecture](workflow-architecture) — design and architecture +- [Workflow Inventory](workflow-inventory) — complete inventory of all workflows + +## Branch & Issue Management + +- [Dev Branch Tracking](dev-branch-tracking) — manual issue creation for dev branches, auto-creation for rc branches +- [Sub-Issue Management](sub-issue-management) — hierarchical issue tracking + +## Update Server + +- [Update Server](update-server) — multi-entry Joomla updates.xml with stability filtering +- [Reserve Dolibarr Module ID](reserve-dolibarr-module-id) — module ID reservation + +## Platform Workflow Matrix + +| Workflow | Joomla | Dolibarr | Generic | +|----------|--------|----------|---------| +| `auto-release.yml` | Yes (ZIP + SHA-256 + updates.xml) | Yes (update.txt) | Yes | +| `deploy-dev.yml` | No | Yes | Yes | +| `deploy-demo.yml` | No | Yes | Yes | +| `deploy-manual.yml` | Yes | No | No | +| `update-server.yml` | Yes | No | No | +| `ci-joomla.yml` | Yes | No | No | +| `ci-dolibarr.yml` | No | Yes | No | +| `repo_health.yml` | Yes | Yes | Yes | +| `changelog-validation.yml` | Yes | Yes | Yes | + +## Metadata + +- **Document Type:** index +- **Last Updated:** 2026-04-07 +- **Version:** 04.06.00 +--- -# workflows +*Repo: [moko-platform](https://git.mokoconsulting.tech/MokoConsulting/moko-platform) · [moko-platform wiki](https://git.mokoconsulting.tech/MokoConsulting/moko-platform/wiki/Home)* -## Purpose +| Field | Value | +|---|---| +| Minimum Version | 04.07.00 | +| Platform | all | +| Applies To | All repositories | -Documentation for all Gitea Actions workflows used across governed repositories. - -## Deployment Workflows - -### Dolibarr + Generic (automatic FTP deploy) - -- [Dev Deployment](dev-deployment) — deploy to dev FTP on push to `dev/**`, `alpha/**`, `beta/**`, or `rc/**` -- [Demo Deployment](demo-deployment) — deploy to demo FTP on push to `main` - -> **Note:** `deploy-rs.yml` is **retired**. RS deployment is handled via the release pipeline only. See [RS Deployment (deprecated)](rs-deployment). - -### Joomla (no automatic FTP deploy) - -Joomla repos use GitHub Release ZIPs via `auto-release.yml` + `updates.xml`. No automatic FTP deploy. - -- [Deploy Manual](deploy-manual) — manual workflow_dispatch FTP deploy for Joomla dev testing - -## Release & Version Workflows - -- [Auto Release](auto-release) — platform-specific GitHub Release on push to main (generic, Joomla, Dolibarr) -- [Build Release](build-release) — build release artifacts -- [Release System](release-system) — end-to-end release lifecycle (dev → rc → main) -- [Changelog Management](changelog-management) — automated changelog generation -- [Changelog Validation](changelog-validation) — validates CHANGELOG.md format on PR - -## Client Repositories - -- [Client Repo Standards](client-repos) — naming, privacy, structure, deployment for client-* repos - -## CI & Compliance Workflows - -- [CI Joomla](ci-joomla) — Joomla-specific CI checks (manifest validation, language files, XML lint) -- [CI Dolibarr](ci-dolibarr) — Dolibarr-specific CI checks (module descriptor, PHP lint) -- [Standards Compliance](standards-compliance) — enterprise standards validation -- [Repo Health](repo-health) — platform-aware repository health checks -- [Shared Workflows](shared-workflows) — reusable workflow templates -- [Reusable Workflows](reusable-workflows) — reusable workflow reference -- [Workflow Architecture](workflow-architecture) — design and architecture -- [Workflow Inventory](workflow-inventory) — complete inventory of all workflows - -## Branch & Issue Management - -- [Dev Branch Tracking](dev-branch-tracking) — manual issue creation for dev branches, auto-creation for rc branches -- [Sub-Issue Management](sub-issue-management) — hierarchical issue tracking - -## Update Server - -- [Update Server](update-server) — multi-entry Joomla updates.xml with stability filtering -- [Reserve Dolibarr Module ID](reserve-dolibarr-module-id) — module ID reservation - -## Platform Workflow Matrix - -| Workflow | Joomla | Dolibarr | Generic | -|----------|--------|----------|---------| -| `auto-release.yml` | Yes (ZIP + SHA-256 + updates.xml) | Yes (update.txt) | Yes | -| `deploy-dev.yml` | No | Yes | Yes | -| `deploy-demo.yml` | No | Yes | Yes | -| `deploy-manual.yml` | Yes | No | No | -| `update-server.yml` | Yes | No | No | -| `ci-joomla.yml` | Yes | No | No | -| `ci-dolibarr.yml` | No | Yes | No | -| `repo_health.yml` | Yes | Yes | Yes | -| `changelog-validation.yml` | Yes | Yes | Yes | - -## Metadata - -- **Document Type:** index -- **Last Updated:** 2026-04-07 -- **Version:** 05.00.00 +| Revision | Date | Author | Description | +|---|---|---|---| +| 1.0 | 2026-05-08 | Moko Consulting | Initial version | diff --git a/moko-platform/workflows-release-system.-.-.md b/moko-platform/workflows-release-system.-.-.md index 8ae1b6c..a677dd0 100644 --- a/moko-platform/workflows-release-system.-.-.md +++ b/moko-platform/workflows-release-system.-.-.md @@ -1,200 +1,213 @@ ← [Home](Home) -[![moko-platform](https://img.shields.io/badge/moko-platform-05.00.00-orange)](https://git.mokoconsulting.tech/MokoConsulting/moko-platform) - -# Release System - -## Overview - -The moko-platform release system uses a branch-based pipeline with platform-specific packaging. Releases flow through development, optional alpha/beta testing, release candidate, and production stages with automated GitHub Release creation, version archiving, and platform-aware asset publishing. - -## Release Lifecycle - -### Version Numbering - -All version files use three-part format: `XX.YY.ZZ` - -- **Patch 00** (`XX.YY.00`) = development only, no release created -- **Patch 01** (`XX.YY.01`) = first release for a minor version -- **Patch 02+** = subsequent releases (bug fixes, improvements) - -### Branch Flow - -``` -dev → [alpha] → [beta] → rc → version/XX → main → dev - optional (integration) (production) (feedback) -``` - -1. **`dev/XX.YY`** or **`dev/feature-name`** — Active development. Patch is 00. No release. -2. **`alpha/XX.YY.ZZ`** — *(Optional)* Early internal testing. Can be skipped — dev can go straight to rc. -3. **`beta/XX.YY.ZZ`** — *(Optional)* Broader external testing. Can be skipped — dev can go straight to rc. -4. **`rc/XX.YY.ZZ`** — Release candidate. Three-part version required (patch >= 01). Auto-creates tracking issue + draft GitHub Release. -5. **`version/XX`** — Major version integration branch (major number only, e.g., `version/04`). All minors and patches flow into the same major branch. -6. **`main`** — Production. Push triggers `auto-release.yml` which publishes the GitHub Release, creates/updates the major tag, and auto-bumps patch. -7. **`main` merges back to `dev`** — Completes the cycle. Ensures dev has the latest production state. - -### Release Tags - -Each stability level has its own GitHub Release tag: - -| Tag | Stability | Contents | -|-----|-----------|----------| -| `development` | Development | Dev ZIPs | -| `alpha` | Alpha | Alpha ZIPs | -| `beta` | Beta | Beta ZIPs | -| `release-candidate` | RC | RC ZIPs | -| `vXX` | Stable production | Stable ZIPs (major only, e.g., `v04`) | - -- The `vXX` production tag is **major only** — one release per major version -## Workflow Location (v2)All workflows MUST be in `.gitea/workflows/` only. Gitea Actions does not run workflows from `.gitea/workflows/`. Having files in `.gitea/workflows/` creates ghost queued runs that block the runner.## Stream TagsReleases use stream-based git tags, NOT version numbers:- `stable` — production release- `release-candidate` — RC testing- `beta` — feature-complete stability testing- `alpha` — early testing- `development` — unstable dev buildsTo trigger a release, push the appropriate stream tag: `git tag -f stable && git push origin stable --force`## Cascade LogicEach stability level cascades to all lower levels in updates.xml:- **stable** → updates development, alpha, beta, rc, stable- **rc** → updates development, alpha, beta, rc- **beta** → updates development, alpha, beta- **alpha** → updates development, alpha- **development** → updates development only## SHA-256 Rules- Never leave `` empty — Joomla fails checksum verification on empty tags- Omit the `` tag entirely if no hash is available- Always set SHA when building a package## creationDateAlways update `` whenever version is bumped — in the manifest AND in updates.xml.## Auto-DetectionThe release workflow (`release.yml`) is fully generic:- `GITEA_REPO` derived from `github.event.repository.name`- `EXT_ELEMENT` auto-detected from the Joomla manifest `` tag- Falls back to manifest filename, then repo name (lowercased)- No per-repo customization needed## Version History (Stable)Stable releases keep up to 5 previous versions in the Gitea release body. -- All minor+patch versions **append** release notes and ZIP assets to the same `vXX` release -- No minor or patch production tags are created -- Example: versions `04.01.01`, `04.02.00`, `04.03.05` all update the same `v04` release -- Pre-release tags (`development`, `alpha`, `beta`, `release-candidate`) are updated in-place - -### Standard Release Process - -1. **Start development**: Create `dev/XX.YY` branch from main -2. **Develop**: Work on the dev branch with version set to `XX.YY.00` -3. **Alpha testing** *(optional)*: Create `alpha/XX.YY.ZZ` branch from dev for early internal testing. Can be skipped. -4. **Beta testing** *(optional)*: Create `beta/XX.YY.ZZ` branch from alpha (or dev) for broader external testing. Can be skipped. -5. **Create RC**: Create `rc/XX.YY.01` branch from beta, alpha, or dev. This auto-creates a tracking issue with 5 sub-issues and a draft GitHub Release -6. **Test RC**: Fix bugs on the RC branch. Deploy to dev server for final testing -7. **Merge to version/XX**: Merge RC to the `version/XX` major integration branch -8. **Merge to main**: Merge `version/XX` to main via PR. `auto-release.yml` fires: - - Publishes the draft release (or creates new one) - - Uploads platform-specific assets (ZIP for Joomla, etc.) - - Creates/updates the `vXX` tag - - Auto-bumps patch version with `[skip ci]` commit -9. **Feedback loop**: Main merges back to dev to start the next cycle - -## Platform-Specific Pipelines - -### Generic Repos - -- `auto-release.yml`: Creates GitHub Release with changelog notes, `vXX` tag -- `deploy-dev.yml`: FTP deploy on push to `dev/**`, `alpha/**`, `beta/**`, or `rc/**` -- `deploy-demo.yml`: FTP deploy on push to `main` -- `changelog-validation.yml`: Validates CHANGELOG.md format on PRs - -### Joomla Repos (waas-component) - -Joomla repos do **not** use automatic FTP deploy workflows. Distribution is via `updates.xml` + GitHub Release ZIPs + manual dev deploy. - -- `auto-release.yml`: Builds ZIP from `src/`, uploads to major release, writes SHA-256 in `updates.xml` -- `update-server.yml`: Writes dev/alpha/beta/rc entries to `updates.xml` on branch push -- `deploy-manual.yml`: Manual workflow_dispatch FTP deploy for dev testing (no automatic deploy) -- `ci-joomla.yml`: Manifest validation, language file checks, XML lint -- `repo_health.yml`: Platform-aware health checks -- `changelog-validation.yml`: Validates CHANGELOG.md format on PRs - -### Dolibarr Repos (crm-module, crm-platform) - -- `auto-release.yml`: Creates GitHub Release, updates `update.txt` and module descriptor version -- `deploy-dev.yml` / `deploy-demo.yml`: FTP deploy -- `publish-to-mokodolimods.yml`: Publishes to MokoDolimods marketplace (crm-module only) -- `ci-dolibarr.yml`: Module descriptor validation, PHP lint -- `repo_health.yml`: Platform-aware health checks -- `changelog-validation.yml`: Validates CHANGELOG.md format on PRs - -## Version Format Summary - -| Context | Format | Example | -|---------|--------|---------| -| Version files | `XX.YY.ZZ` (three-part always) | `05.00.00` | -| Dev branches | `XX.YY` or `XX.YY.ZZ` or `feature-name` | `dev/04.06`, `dev/sidebar-fix` | -| Alpha branches | `XX.YY.ZZ` (three-part, optional stage) | `alpha/04.06.01` | -| Beta branches | `XX.YY.ZZ` (three-part, optional stage) | `beta/04.06.01` | -| RC branches | `XX.YY.ZZ` (three-part required) | `rc/04.06.01` | -| Version branches | `XX` (major only) | `version/04` | -| Release tags (stable) | `vXX` (major only) | `v04` | -| Release tags (pre) | Named per stability level | `development`, `alpha`, `beta`, `release-candidate` | - -## Version Detection - -The `auto-release.yml` workflow reads the version from the `VERSION:` field in the README.md FILE INFORMATION block. This is the single source of truth for the release version. - -## Skipping Releases - -To prevent automatic release creation, include `[skip ci]` in your commit message: - -```bash -git commit -m "docs: update README [skip ci]" -``` - -Commits by `gitea-actions[bot]` are also skipped automatically (e.g., auto-bump commits). - -## Architecture - -### Full Release Cycle - -``` -┌─────────────────────────────────────────────────────────────────┐ -│ dev → [alpha] → [beta] → rc → version/XX → main │ -│ optional optional │ │ -│ └──→ dev│ -└─────────────────────────────────────────────────────────────────┘ -``` - -### Auto-Release Pipeline (on push to main) - -``` -┌──────────────────────────────────────────────────────────┐ -│ Push to main branch │ -│ (version in README.md FILE INFORMATION) │ -└────────────────────┬─────────────────────────────────────┘ - │ - ▼ -┌──────────────────────────────────────────────────────────┐ -│ auto-release.yml (Detect + Route) │ -│ • Read VERSION from README.md │ -│ • Check if vXX tag exists (major-only) │ -│ • Detect platform (.mokostandards → platform field) │ -└────────────────────┬─────────────────────────────────────┘ - │ - ┌──────────┼──────────┐ - ▼ ▼ ▼ - ┌──────────┐ ┌──────────┐ ┌──────────────┐ - │ Generic │ │ Joomla │ │ Dolibarr │ - │ │ │ │ │ │ - │ Tag vXX │ │ Build ZIP│ │ Update │ - │ Release │ │ SHA-256 │ │ update.txt │ - │ notes │ │ update │ │ mod*.class │ - │ │ │ .xml │ │ Tag + release│ - └──────────┘ └──────────┘ └──────────────┘ - │ - ▼ -┌──────────────────────────────────────────────────────────┐ -│ GitHub Release (one per major) │ -│ • Create or update vXX release │ -│ • Append release notes for this minor.patch │ -│ • Upload ZIP assets (Joomla) │ -│ • Auto-bump patch version ([skip ci]) │ -│ • Main merges back to dev (feedback loop) │ -└──────────────────────────────────────────────────────────┘ -``` - -## Configuration Files - -- `.gitea/workflows/auto-release.yml` - Main release workflow (platform-aware) -- `.gitea/workflows/update-server.yml` - Joomla updates.xml generation for dev/alpha/beta/rc -- `.gitea/workflows/changelog-validation.yml` - CHANGELOG.md format validation -- `.mokostandards` - Platform configuration (`platform: joomla|dolibarr|generic`) -- `README.md` - VERSION field (single source of truth) -- `CHANGELOG.md` - Release notes source - -## Best Practices - -1. **Patch 00 is always dev** — never release from patch 00 -2. **RC before release** — always go through `rc/` before merging to main (alpha/beta are optional) -3. **Alpha and beta are optional** — dev can go straight to rc when internal/external testing stages are not needed -4. **One major release object** — all minor+patch append to the same `vXX` GitHub Release -5. **Let auto-bump handle patch** — don't manually bump patch on main -6. **Write clear changelog entries** before creating RC -7. **Test RC on dev server** — RC branches deploy to dev FTP (Dolibarr/Generic) or generate dev updates.xml entries (Joomla) -8. **Main feeds back to dev** — always merge main back to dev after a release to start the next cycle - +[![moko-platform](https://img.shields.io/badge/moko-platform-04.06.00-orange)](https://git.mokoconsulting.tech/MokoConsulting/moko-platform) + +# Release System + +## Overview + +The moko-platform release system uses a branch-based pipeline with platform-specific packaging. Releases flow through development, optional alpha/beta testing, release candidate, and production stages with automated GitHub Release creation, version archiving, and platform-aware asset publishing. + +## Release Lifecycle + +### Version Numbering + +All version files use three-part format: `XX.YY.ZZ` + +- **Patch 00** (`XX.YY.00`) = development only, no release created +- **Patch 01** (`XX.YY.01`) = first release for a minor version +- **Patch 02+** = subsequent releases (bug fixes, improvements) + +### Branch Flow + +``` +dev → [alpha] → [beta] → rc → version/XX → main → dev + optional (integration) (production) (feedback) +``` + +1. **`dev/XX.YY`** or **`dev/feature-name`** — Active development. Patch is 00. No release. +2. **`alpha/XX.YY.ZZ`** — *(Optional)* Early internal testing. Can be skipped — dev can go straight to rc. +3. **`beta/XX.YY.ZZ`** — *(Optional)* Broader external testing. Can be skipped — dev can go straight to rc. +4. **`rc/XX.YY.ZZ`** — Release candidate. Three-part version required (patch >= 01). Auto-creates tracking issue + draft GitHub Release. +5. **`version/XX`** — Major version integration branch (major number only, e.g., `version/04`). All minors and patches flow into the same major branch. +6. **`main`** — Production. Push triggers `auto-release.yml` which publishes the GitHub Release, creates/updates the major tag, and auto-bumps patch. +7. **`main` merges back to `dev`** — Completes the cycle. Ensures dev has the latest production state. + +### Release Tags + +Each stability level has its own GitHub Release tag: + +| Tag | Stability | Contents | +|-----|-----------|----------| +| `development` | Development | Dev ZIPs | +| `alpha` | Alpha | Alpha ZIPs | +| `beta` | Beta | Beta ZIPs | +| `release-candidate` | RC | RC ZIPs | +| `vXX` | Stable production | Stable ZIPs (major only, e.g., `v04`) | + +- The `vXX` production tag is **major only** — one release per major version +## Workflow Location (v2)All workflows MUST be in `.gitea/workflows/` only. Gitea Actions does not run workflows from `.gitea/workflows/`. Having files in `.gitea/workflows/` creates ghost queued runs that block the runner.## Stream TagsReleases use stream-based git tags, NOT version numbers:- `stable` — production release- `release-candidate` — RC testing- `beta` — feature-complete stability testing- `alpha` — early testing- `development` — unstable dev buildsTo trigger a release, push the appropriate stream tag: `git tag -f stable && git push origin stable --force`## Cascade LogicEach stability level cascades to all lower levels in updates.xml:- **stable** → updates development, alpha, beta, rc, stable- **rc** → updates development, alpha, beta, rc- **beta** → updates development, alpha, beta- **alpha** → updates development, alpha- **development** → updates development only## SHA-256 Rules- Never leave `` empty — Joomla fails checksum verification on empty tags- Omit the `` tag entirely if no hash is available- Always set SHA when building a package## creationDateAlways update `` whenever version is bumped — in the manifest AND in updates.xml.## Auto-DetectionThe release workflow (`release.yml`) is fully generic:- `GITEA_REPO` derived from `github.event.repository.name`- `EXT_ELEMENT` auto-detected from the Joomla manifest `` tag- Falls back to manifest filename, then repo name (lowercased)- No per-repo customization needed## Version History (Stable)Stable releases keep up to 5 previous versions in the Gitea release body. +- All minor+patch versions **append** release notes and ZIP assets to the same `vXX` release +- No minor or patch production tags are created +- Example: versions `04.01.01`, `04.02.00`, `04.03.05` all update the same `v04` release +- Pre-release tags (`development`, `alpha`, `beta`, `release-candidate`) are updated in-place + +### Standard Release Process + +1. **Start development**: Create `dev/XX.YY` branch from main +2. **Develop**: Work on the dev branch with version set to `XX.YY.00` +3. **Alpha testing** *(optional)*: Create `alpha/XX.YY.ZZ` branch from dev for early internal testing. Can be skipped. +4. **Beta testing** *(optional)*: Create `beta/XX.YY.ZZ` branch from alpha (or dev) for broader external testing. Can be skipped. +5. **Create RC**: Create `rc/XX.YY.01` branch from beta, alpha, or dev. This auto-creates a tracking issue with 5 sub-issues and a draft GitHub Release +6. **Test RC**: Fix bugs on the RC branch. Deploy to dev server for final testing +7. **Merge to version/XX**: Merge RC to the `version/XX` major integration branch +8. **Merge to main**: Merge `version/XX` to main via PR. `auto-release.yml` fires: + - Publishes the draft release (or creates new one) + - Uploads platform-specific assets (ZIP for Joomla, etc.) + - Creates/updates the `vXX` tag + - Auto-bumps patch version with `[skip ci]` commit +9. **Feedback loop**: Main merges back to dev to start the next cycle + +## Platform-Specific Pipelines + +### Generic Repos + +- `auto-release.yml`: Creates GitHub Release with changelog notes, `vXX` tag +- `deploy-dev.yml`: FTP deploy on push to `dev/**`, `alpha/**`, `beta/**`, or `rc/**` +- `deploy-demo.yml`: FTP deploy on push to `main` +- `changelog-validation.yml`: Validates CHANGELOG.md format on PRs + +### Joomla Repos (waas-component) + +Joomla repos do **not** use automatic FTP deploy workflows. Distribution is via `updates.xml` + GitHub Release ZIPs + manual dev deploy. + +- `auto-release.yml`: Builds ZIP from `src/`, uploads to major release, writes SHA-256 in `updates.xml` +- `update-server.yml`: Writes dev/alpha/beta/rc entries to `updates.xml` on branch push +- `deploy-manual.yml`: Manual workflow_dispatch FTP deploy for dev testing (no automatic deploy) +- `ci-joomla.yml`: Manifest validation, language file checks, XML lint +- `repo_health.yml`: Platform-aware health checks +- `changelog-validation.yml`: Validates CHANGELOG.md format on PRs + +### Dolibarr Repos (crm-module, crm-platform) + +- `auto-release.yml`: Creates GitHub Release, updates `update.txt` and module descriptor version +- `deploy-dev.yml` / `deploy-demo.yml`: FTP deploy +- `publish-to-mokodolimods.yml`: Publishes to MokoDolimods marketplace (crm-module only) +- `ci-dolibarr.yml`: Module descriptor validation, PHP lint +- `repo_health.yml`: Platform-aware health checks +- `changelog-validation.yml`: Validates CHANGELOG.md format on PRs + +## Version Format Summary + +| Context | Format | Example | +|---------|--------|---------| +| Version files | `XX.YY.ZZ` (three-part always) | `04.06.00` | +| Dev branches | `XX.YY` or `XX.YY.ZZ` or `feature-name` | `dev/04.06`, `dev/sidebar-fix` | +| Alpha branches | `XX.YY.ZZ` (three-part, optional stage) | `alpha/04.06.01` | +| Beta branches | `XX.YY.ZZ` (three-part, optional stage) | `beta/04.06.01` | +| RC branches | `XX.YY.ZZ` (three-part required) | `rc/04.06.01` | +| Version branches | `XX` (major only) | `version/04` | +| Release tags (stable) | `vXX` (major only) | `v04` | +| Release tags (pre) | Named per stability level | `development`, `alpha`, `beta`, `release-candidate` | + +## Version Detection + +The `auto-release.yml` workflow reads the version from the `VERSION:` field in the README.md FILE INFORMATION block. This is the single source of truth for the release version. + +## Skipping Releases + +To prevent automatic release creation, include `[skip ci]` in your commit message: + +```bash +git commit -m "docs: update README [skip ci]" +``` + +Commits by `gitea-actions[bot]` are also skipped automatically (e.g., auto-bump commits). + +## Architecture + +### Full Release Cycle + +``` +┌─────────────────────────────────────────────────────────────────┐ +│ dev → [alpha] → [beta] → rc → version/XX → main │ +│ optional optional │ │ +│ └──→ dev│ +└─────────────────────────────────────────────────────────────────┘ +``` + +### Auto-Release Pipeline (on push to main) + +``` +┌──────────────────────────────────────────────────────────┐ +│ Push to main branch │ +│ (version in README.md FILE INFORMATION) │ +└────────────────────┬─────────────────────────────────────┘ + │ + ▼ +┌──────────────────────────────────────────────────────────┐ +│ auto-release.yml (Detect + Route) │ +│ • Read VERSION from README.md │ +│ • Check if vXX tag exists (major-only) │ +│ • Detect platform (.mokostandards → platform field) │ +└────────────────────┬─────────────────────────────────────┘ + │ + ┌──────────┼──────────┐ + ▼ ▼ ▼ + ┌──────────┐ ┌──────────┐ ┌──────────────┐ + │ Generic │ │ Joomla │ │ Dolibarr │ + │ │ │ │ │ │ + │ Tag vXX │ │ Build ZIP│ │ Update │ + │ Release │ │ SHA-256 │ │ update.txt │ + │ notes │ │ update │ │ mod*.class │ + │ │ │ .xml │ │ Tag + release│ + └──────────┘ └──────────┘ └──────────────┘ + │ + ▼ +┌──────────────────────────────────────────────────────────┐ +│ GitHub Release (one per major) │ +│ • Create or update vXX release │ +│ • Append release notes for this minor.patch │ +│ • Upload ZIP assets (Joomla) │ +│ • Auto-bump patch version ([skip ci]) │ +│ • Main merges back to dev (feedback loop) │ +└──────────────────────────────────────────────────────────┘ +``` + +## Configuration Files + +- `.gitea/workflows/auto-release.yml` - Main release workflow (platform-aware) +- `.gitea/workflows/update-server.yml` - Joomla updates.xml generation for dev/alpha/beta/rc +- `.gitea/workflows/changelog-validation.yml` - CHANGELOG.md format validation +- `.mokostandards` - Platform configuration (`platform: joomla|dolibarr|generic`) +- `README.md` - VERSION field (single source of truth) +- `CHANGELOG.md` - Release notes source + +## Best Practices + +1. **Patch 00 is always dev** — never release from patch 00 +2. **RC before release** — always go through `rc/` before merging to main (alpha/beta are optional) +3. **Alpha and beta are optional** — dev can go straight to rc when internal/external testing stages are not needed +4. **One major release object** — all minor+patch append to the same `vXX` GitHub Release +5. **Let auto-bump handle patch** — don't manually bump patch on main +6. **Write clear changelog entries** before creating RC +7. **Test RC on dev server** — RC branches deploy to dev FTP (Dolibarr/Generic) or generate dev updates.xml entries (Joomla) +8. **Main feeds back to dev** — always merge main back to dev after a release to start the next cycle + +--- + +**Last Updated**: 2026-04-07 +**Maintained by**: Moko Consulting Infrastructure Team --- -**Last Updated**: 2026-04-07 -**Maintained by**: Moko Consulting Infrastructure Team +*Repo: [moko-platform](https://git.mokoconsulting.tech/MokoConsulting/moko-platform) · [moko-platform wiki](https://git.mokoconsulting.tech/MokoConsulting/moko-platform/wiki/Home)* + +| Field | Value | +|---|---| +| Minimum Version | 04.07.00 | +| Platform | all | +| Applies To | All repositories | + +| Revision | Date | Author | Description | +|---|---|---|---| +| 1.0 | 2026-05-08 | Moko Consulting | Initial version | diff --git a/moko-platform/workflows-renovate.-.-.md b/moko-platform/workflows-renovate.-.-.md index f205a32..4be0995 100644 --- a/moko-platform/workflows-renovate.-.-.md +++ b/moko-platform/workflows-renovate.-.-.md @@ -1,71 +1,84 @@ ← [Home](Home) -[![moko-platform](https://img.shields.io/badge/moko-platform-05.00.00-orange)](https://git.mokoconsulting.tech/MokoConsulting/moko-platform) - -# Renovate Dependency Updates - -**Status**: ✅ Active | **Version**: 01.00.00 | **Last Updated**: 2026-05-07 - -## Overview - -Automated dependency update management using [Renovate](https://docs.renovatebot.com/). Runs centrally from moko-platform and creates PRs for outdated dependencies across all governed repos. - -## Architecture - -- **Central runner**: `renovate.yml` workflow in moko-platform scans all repos -- **Per-repo config**: `renovate.json` in each repo controls update behavior -- **Supported managers**: Composer (PHP), npm (JavaScript) - -## Schedule - -| Trigger | When | -|---------|------| -| Scheduled | Weekly Wednesday 04:00 UTC | -| Manual | Dispatch with optional repo filter and dry-run | - -## Update Behavior - -| Update Type | Action | -|-------------|--------| -| Patch (x.x.Y) | Auto-merge if CI passes | -| Minor (x.Y.0) | PR created, manual review required | -| Major (Y.0.0) | PR created, manual review required | - -## Per-Repo Configuration - -Each repo has a `renovate.json` that extends the recommended config: - -```json -{ - "extends": ["config:recommended", "schedule:weekly"], - "automerge": false, - "packageRules": [ - { "matchUpdateTypes": ["patch"], "automerge": true } - ] -} -``` - -Override in any repo by editing its `renovate.json`. - -## Inputs (Manual Dispatch) - -| Input | Default | Description | -|-------|---------|-------------| -| `repos` | all | Comma-separated repo names | -| `dry_run` | false | Log only, no PRs created | - -## Excluded Repos - -Same exclusion list as other centralized workflows (platform/standards/template repos). - -## Related Documentation - -- [Security Audit](security-audit) -- [Secret Scanning](secret-scanning) -- [Bulk Repository Sync](bulk-repo-sync) - -## Changelog - -| Version | Date | Changes | -|---------|------|---------| +[![moko-platform](https://img.shields.io/badge/moko-platform-04.06.00-orange)](https://git.mokoconsulting.tech/MokoConsulting/moko-platform) + +# Renovate Dependency Updates + +**Status**: ✅ Active | **Version**: 01.00.00 | **Last Updated**: 2026-05-07 + +## Overview + +Automated dependency update management using [Renovate](https://docs.renovatebot.com/). Runs centrally from moko-platform and creates PRs for outdated dependencies across all governed repos. + +## Architecture + +- **Central runner**: `renovate.yml` workflow in moko-platform scans all repos +- **Per-repo config**: `renovate.json` in each repo controls update behavior +- **Supported managers**: Composer (PHP), npm (JavaScript) + +## Schedule + +| Trigger | When | +|---------|------| +| Scheduled | Weekly Wednesday 04:00 UTC | +| Manual | Dispatch with optional repo filter and dry-run | + +## Update Behavior + +| Update Type | Action | +|-------------|--------| +| Patch (x.x.Y) | Auto-merge if CI passes | +| Minor (x.Y.0) | PR created, manual review required | +| Major (Y.0.0) | PR created, manual review required | + +## Per-Repo Configuration + +Each repo has a `renovate.json` that extends the recommended config: + +```json +{ + "extends": ["config:recommended", "schedule:weekly"], + "automerge": false, + "packageRules": [ + { "matchUpdateTypes": ["patch"], "automerge": true } + ] +} +``` + +Override in any repo by editing its `renovate.json`. + +## Inputs (Manual Dispatch) + +| Input | Default | Description | +|-------|---------|-------------| +| `repos` | all | Comma-separated repo names | +| `dry_run` | false | Log only, no PRs created | + +## Excluded Repos + +Same exclusion list as other centralized workflows (platform/standards/template repos). + +## Related Documentation + +- [Security Audit](security-audit) +- [Secret Scanning](secret-scanning) +- [Bulk Repository Sync](bulk-repo-sync) + +## Changelog + +| Version | Date | Changes | +|---------|------|---------| | 01.00.00 | 2026-05-07 | Initial release — centralized Renovate runner | +--- + +*Repo: [moko-platform](https://git.mokoconsulting.tech/MokoConsulting/moko-platform) · [moko-platform wiki](https://git.mokoconsulting.tech/MokoConsulting/moko-platform/wiki/Home)* + +| Field | Value | +|---|---| +| Minimum Version | 04.07.00 | +| Platform | all | +| Applies To | All repositories | + +| Revision | Date | Author | Description | +|---|---|---|---| +| 1.0 | 2026-05-08 | Moko Consulting | Initial version | diff --git a/moko-platform/workflows-reusable-workflows.-.-.md b/moko-platform/workflows-reusable-workflows.-.-.md index 0e7f1a4..e46c1a3 100644 --- a/moko-platform/workflows-reusable-workflows.-.-.md +++ b/moko-platform/workflows-reusable-workflows.-.-.md @@ -1,553 +1,566 @@ ← [Home](Home) -[![moko-platform](https://img.shields.io/badge/moko-platform-05.00.00-orange)](https://git.mokoconsulting.tech/MokoConsulting/moko-platform) - -# Reusable Workflows - -moko-platform provides seven reusable Gitea Actions workflows that enable consistent CI/CD across all organization repositories, with automatic project type detection for Joomla extensions, Dolibarr modules, and generic applications. - -## Quick Start - -```yaml -# Basic quality check -jobs: - quality: - uses: MokoConsulting/moko-platform/.gitea/workflows/reusable-php-quality.yml@main - -# Type-aware build and release - build: - uses: MokoConsulting/moko-platform/.gitea/workflows/reusable-build.yml@main - - release: - uses: MokoConsulting/moko-platform/.gitea/workflows/reusable-release.yml@main - with: - version: '1.0.0' -``` - -## Workflow Categories - -### Quality & Testing Workflows -- **reusable-php-quality.yml** - PHP code quality analysis (PHPCS, PHPStan, Psalm) -- **reusable-joomla-testing.yml** - Joomla extension testing with matrix PHP/Joomla versions -- **reusable-ci-validation.yml** - Repository standards validation - -### Repository Maintenance Workflows -- **reusable-branch-cleanup.yml** - Automated cleanup of stale and merged branches - -### Type-Aware Orchestration Workflows -- **reusable-project-detector.yml** - Automatic project type detection -- **reusable-build.yml** - Universal build for all project types -- **reusable-release.yml** - Type-aware release creation and packaging -- **reusable-deploy.yml** - Multi-environment deployment - -> **Type-Aware Workflows** automatically detect whether your project is a Joomla extension, Dolibarr module, or generic application, and apply appropriate build/release/deploy steps. This enables a single workflow definition to work across all repositories. - ---- - -## Quality & Testing Workflows - -### PHP Quality Analysis - -Runs comprehensive PHP code quality checks using PHPCS, PHPStan, and Psalm with configurable standards and analysis levels. - -**Usage:** -```yaml -jobs: - quality: - uses: MokoConsulting/moko-platform/.gitea/workflows/reusable-php-quality.yml@main - with: - php-versions: '["8.1", "8.2"]' - tools: '["phpcs", "phpstan", "psalm"]' - phpcs-standard: 'PSR12' - phpstan-level: '6' -``` - -**Key Inputs:** -- `php-versions` (string) - JSON array of PHP versions, default: `["7.4", "8.0", "8.1", "8.2"]` -- `tools` (string) - JSON array of tools, default: `["phpcs", "phpstan", "psalm"]` -- `phpcs-standard` (string) - Coding standard, default: `PSR12` -- `phpstan-level` (string) - Analysis level 0-9, default: `5` -- `fail-on-error` (boolean) - Fail on errors, default: `true` - -**Outputs:** `quality-score` - Overall quality score percentage (0-100) - -### Joomla Testing - -Matrix testing for Joomla extensions across PHP and Joomla versions with PHPUnit, MySQL, and code coverage support. - -**Usage:** -```yaml -jobs: - test: - uses: MokoConsulting/moko-platform/.gitea/workflows/reusable-joomla-testing.yml@main - with: - php-versions: '["8.1", "8.2"]' - joomla-versions: '["4.4", "5.0", "5.1"]' - coverage: true - secrets: - CODECOV_TOKEN: ${{ secrets.CODECOV_TOKEN }} -``` - -**Key Inputs:** -- `php-versions` (string) - JSON array, default: `["7.4", "8.0", "8.1", "8.2"]` -- `joomla-versions` (string) - JSON array, default: `["4.4", "5.0", "5.1"]` -- `coverage` (boolean) - Enable coverage, default: `false` -- `run-integration-tests` (boolean) - Run integration tests, default: `true` - -> Automatically excludes incompatible combinations (e.g., PHP 7.4 + Joomla 5.x) - -### CI Validation - -Repository standards validation with configurable profiles (basic, full, strict). - -**Usage:** -```yaml -jobs: - validate: - uses: MokoConsulting/moko-platform/.gitea/workflows/reusable-ci-validation.yml@main - with: - profile: 'full' - validate-security: true -``` - -**Validation Profiles:** -- **basic** - Manifest, XML, PHP syntax, security checks -- **full** - Basic + changelog, license headers, language structure, paths, whitespace -- **strict** - Full validation with fail-on-warnings enabled - -**Key Inputs:** -- `profile` (string) - Validation profile, default: `basic` -- `validate-manifests` (boolean) - Validate XML manifests, default: `true` -- `validate-changelogs` (boolean) - Validate CHANGELOG.md, default: `true` -- `validate-licenses` (boolean) - Validate license headers, default: `true` -- `validate-security` (boolean) - Security checks, default: `true` -- `fail-on-warnings` (boolean) - Fail on warnings, default: `false` - ---- - -## Repository Maintenance Workflows - -### Branch Cleanup - -Automatically cleans up stale and merged branches with configurable exclusion patterns and dry-run support. - -**Usage:** -```yaml -jobs: - cleanup: - uses: MokoConsulting/moko-platform/.gitea/workflows/reusable-branch-cleanup.yml@main - with: - stale-days: 90 - delete-merged: true - delete-stale: true - dry-run: false - permissions: - contents: write -``` - -**Key Inputs:** -- `stale-days` (number) - Days before branch is stale, default: `90` -- `delete-merged` (boolean) - Delete merged branches, default: `true` -- `delete-stale` (boolean) - Delete stale branches, default: `true` -- `dry-run` (boolean) - Preview without deleting, default: `false` -- `exclude-patterns` (string) - JSON array of regex patterns to exclude, default: `["main", "master", "develop", "dev", "dev/.*", "rc/.*", "release/.*", "staging", "production"]` -- `exclude-prefix` (string) - Comma-separated prefixes to exclude, default: `"dependabot/,renovate/"` - -**Features:** -- Detects and deletes branches merged into default branch -- Identifies stale branches based on last commit date -- Configurable exclusion patterns (regex and prefix-based) -- Dry-run mode for previewing changes -- Detailed summary of deleted and failed branches - -**Example with custom exclusions:** -```yaml -jobs: - cleanup: - uses: MokoConsulting/moko-platform/.gitea/workflows/reusable-branch-cleanup.yml@main - with: - stale-days: 60 - delete-merged: true - delete-stale: true - dry-run: false - exclude-patterns: '["main", "master", "develop", "hotfix/.*"]' - exclude-prefix: 'dependabot/,renovate/,feature/' -``` - ---- - -## Type-Aware Orchestration Workflows - -### Project Type Detection - -Automatically detects project type and provides outputs for downstream workflows. - -**Usage:** -```yaml -jobs: - detect: - uses: MokoConsulting/moko-platform/.gitea/workflows/reusable-project-detector.yml@main -``` - -**Outputs:** -- `project-type` - Detected type: `joomla`, `dolibarr`, or `generic` -- `extension-type` - Extension type: `component`, `module`, `plugin`, `template`, `package`, or `application` -- `has-php` - Whether project contains PHP files (true/false) -- `has-node` - Whether project contains package.json (true/false) - -### Type-Aware Build - -Universal build workflow that adapts to project type with automatic dependency management. - -**Usage:** -```yaml -jobs: - build: - uses: MokoConsulting/moko-platform/.gitea/workflows/reusable-build.yml@main - with: - php-version: '8.1' - node-version: '20.x' - upload-artifacts: true -``` - -**Key Inputs:** -- `php-version` (string) - PHP version, default: `8.1` -- `node-version` (string) - Node.js version, default: `20.x` -- `upload-artifacts` (boolean) - Upload build artifacts, default: `true` -- `artifact-name` (string) - Artifact name, default: `build-artifacts` - -**Build Logic:** -- **Joomla:** Installs dependencies, runs npm build if available, prepares extension -- **Dolibarr:** Installs production dependencies, runs build scripts -- **Generic:** Runs npm build, checks for Makefile, executes build commands - -### Type-Aware Release - -Creates releases with type-specific packaging and marketplace support. - -**Usage:** -```yaml -jobs: - release: - uses: MokoConsulting/moko-platform/.gitea/workflows/reusable-release.yml@main - with: - version: '1.0.0' - prerelease: false - create-github-release: true - permissions: - contents: write -``` - -**Key Inputs:** -- `version` (string, **required**) - Release version in semver format -- `prerelease` (boolean) - Mark as pre-release, default: `false` -- `draft` (boolean) - Create as draft, default: `false` -- `create-github-release` (boolean) - Create GitHub release, default: `true` -- `publish-to-marketplace` (boolean) - Publish to marketplace, default: `false` - -**Package Creation:** -- **Joomla/Dolibarr:** ZIP package with manifest version updates -- **Generic:** TAR.GZ package with build artifacts -- All packages include SHA256 and MD5 checksums - -### Type-Aware Deployment - -Multi-environment deployment with type-specific logic and health checks. - -**Usage:** -```yaml -jobs: - deploy: - uses: MokoConsulting/moko-platform/.gitea/workflows/reusable-deploy.yml@main - with: - environment: staging - deployment-method: rsync - health-check-url: https://staging.example.com/health - secrets: - DEPLOY_HOST: ${{ secrets.STAGING_HOST }} - DEPLOY_USER: ${{ secrets.STAGING_USER }} - DEPLOY_KEY: ${{ secrets.STAGING_SSH_KEY }} - DEPLOY_PATH: ${{ secrets.STAGING_PATH }} - permissions: - contents: read - deployments: write -``` - -**Key Inputs:** -- `environment` (string, **required**) - Target: `staging` or `production` -- `deployment-method` (string) - Method: `rsync`, `ssh`, `ftp`, `kubernetes`, `custom`, default: `custom` -- `health-check-url` (string) - URL for post-deployment health check -- `health-check-timeout` (number) - Timeout in seconds, default: `300` - -**Deployment Methods:** -- **rsync:** Direct sync to remote server -- **ssh:** Package transfer and extraction via SSH -- **custom:** Type-specific deployment logic (Joomla extension, Dolibarr module, generic app) - ---- - -## Complete Pipeline Examples - -### Example 1: Type-Aware CI/CD Pipeline - -Single pipeline that works for Joomla, Dolibarr, and generic projects: - -```yaml -name: CI/CD Pipeline - -on: - push: - branches: [main, staging, dev/**] - pull_request: - branches: [main] - release: - types: [published] - -permissions: - contents: write - deployments: write - pull-requests: write - checks: write - -jobs: - # Auto-detect project type - detect: - uses: MokoConsulting/moko-platform/.gitea/workflows/reusable-project-detector.yml@main - - # Validate code - validate: - uses: MokoConsulting/moko-platform/.gitea/workflows/reusable-ci-validation.yml@main - with: - profile: 'full' - - # Check quality (PHP projects only) - quality: - needs: detect - if: needs.detect.outputs.has-php == 'true' - uses: MokoConsulting/moko-platform/.gitea/workflows/reusable-php-quality.yml@main - with: - php-versions: '["8.1", "8.2"]' - - # Test Joomla extensions - test: - needs: [detect, quality] - if: needs.detect.outputs.project-type == 'joomla' - uses: MokoConsulting/moko-platform/.gitea/workflows/reusable-joomla-testing.yml@main - with: - php-versions: '["8.1", "8.2"]' - coverage: true - secrets: - CODECOV_TOKEN: ${{ secrets.CODECOV_TOKEN }} - - # Build (works for all types) - build: - needs: [detect, validate] - uses: MokoConsulting/moko-platform/.gitea/workflows/reusable-build.yml@main - - # Deploy to staging - deploy-staging: - needs: build - if: github.ref == 'refs/heads/staging' - uses: MokoConsulting/moko-platform/.gitea/workflows/reusable-deploy.yml@main - with: - environment: staging - deployment-method: rsync - secrets: inherit - - # Create release on tag - release: - needs: [detect, build] - if: startsWith(github.ref, 'refs/tags/v') - uses: MokoConsulting/moko-platform/.gitea/workflows/reusable-release.yml@main - with: - version: ${{ github.ref_name }} - - # Deploy to production - deploy-production: - needs: release - if: github.event_name == 'release' - uses: MokoConsulting/moko-platform/.gitea/workflows/reusable-deploy.yml@main - with: - environment: production - version: ${{ github.event.release.tag_name }} - secrets: inherit -``` - -### Example 2: Basic Quality and Testing - -Simple quality and testing pipeline: - -```yaml -name: Quality & Test - -on: [push, pull_request] - -jobs: - validate: - uses: MokoConsulting/moko-platform/.gitea/workflows/reusable-ci-validation.yml@main - with: - profile: 'full' - - quality: - needs: validate - uses: MokoConsulting/moko-platform/.gitea/workflows/reusable-php-quality.yml@main - with: - php-versions: '["8.1", "8.2"]' - - test: - needs: quality - uses: MokoConsulting/moko-platform/.gitea/workflows/reusable-joomla-testing.yml@main - with: - coverage: true - secrets: - CODECOV_TOKEN: ${{ secrets.CODECOV_TOKEN }} -``` - ---- - -## Best Practices - -### Version Pinning - -**Recommended:** Pin to main branch for automatic updates -```yaml -uses: MokoConsulting/moko-platform/.gitea/workflows/reusable-php-quality.yml@main -``` - -**Stable:** Pin to specific tag -```yaml -uses: MokoConsulting/moko-platform/.gitea/workflows/reusable-php-quality.yml@v1.0.0 -``` - -**Maximum Stability:** Pin to commit SHA -```yaml -uses: MokoConsulting/moko-platform/.gitea/workflows/reusable-php-quality.yml@abc1234 -``` - -### Secret Management - -**Pass all secrets:** -```yaml -secrets: inherit -``` - -**Pass specific secrets:** -```yaml -secrets: - CODECOV_TOKEN: ${{ secrets.CODECOV_TOKEN }} - DEPLOY_KEY: ${{ secrets.DEPLOY_KEY }} -``` - -### Progressive Adoption - -Start with basic validation, gradually increase strictness: - -```yaml -jobs: - # Dev branches: basic validation - validate-dev: - if: startsWith(github.ref, 'refs/heads/dev/') - uses: MokoConsulting/moko-platform/.gitea/workflows/reusable-ci-validation.yml@main - with: - profile: 'basic' - - # Main branch: strict validation - validate-main: - if: github.ref == 'refs/heads/main' - uses: MokoConsulting/moko-platform/.gitea/workflows/reusable-ci-validation.yml@main - with: - profile: 'strict' - fail-on-warnings: true -``` - ---- - -## Troubleshooting - -### Workflow Not Found -**Error:** `Unable to resolve action MokoConsulting/moko-platform/.gitea/workflows/...` - -**Solution:** Ensure calling repository has access to moko-platform. For private repositories, configure proper access permissions. - -### Missing Secrets -**Error:** `Secret CODECOV_TOKEN is not available` - -**Solution:** Add secret at organization or repository level, or pass explicitly: -```yaml -secrets: - CODECOV_TOKEN: ${{ secrets.CODECOV_TOKEN }} -``` - -### Matrix Job Failures -Random matrix job failures may indicate rate limiting or resource contention. - -**Solution:** Reduce concurrency -```yaml -strategy: - matrix: - php: ['8.1', '8.2'] - max-parallel: 2 # Limit concurrent jobs -``` - -### Health Check Timeout -**Solution:** Increase timeout or verify URL accessibility -```yaml -with: - health-check-timeout: 600 # 10 minutes -``` - ---- - -## Migration from Local Workflows - -**Steps:** -1. Identify workflow type (quality, testing, validation, build, release, deploy) -2. Map your inputs to reusable workflow parameters -3. Update workflow file to call reusable workflow -4. Test on development branch -5. Archive old workflow once validated - -**Example Migration:** - -```yaml -# Before: Local workflow -jobs: - phpcs: - runs-on: ubuntu-latest - steps: - - uses: actions/checkout@v4 - - uses: shivammathur/setup-php@v2 - - run: phpcs --standard=PSR12 src/ - -# After: Reusable workflow -jobs: - quality: - uses: MokoConsulting/moko-platform/.gitea/workflows/reusable-php-quality.yml@main - with: - phpcs-standard: 'PSR12' - tools: '["phpcs"]' -``` - ---- - -## Support & Resources - -**Support:** -- Documentation: [CI Migration Guide](CI_MIGRATION_GUIDE) -- Issues: Open issue in moko-platform repository -- Slack: #devops-support channel - -**Related Documentation:** -- [CI Migration Guide](CI_MIGRATION_GUIDE) - Detailed migration strategy -- [GitHub Reusing Workflows](https://docs.github.com/en/actions/using-workflows/reusing-workflows) -- [Workflow Templates](../../templates/workflows/) - Additional templates - ---- - -## Version History - -| Version | Date | Changes | -|---------|------|---------| -| 02.01.00 | 2026-01-11 | Added reusable-branch-cleanup workflow, standards-compliance workflow | -| 02.00.00 | 2026-01-09 | Consolidated documentation, added type-aware workflows | +[![moko-platform](https://img.shields.io/badge/moko-platform-04.06.00-orange)](https://git.mokoconsulting.tech/MokoConsulting/moko-platform) + +# Reusable Workflows + +moko-platform provides seven reusable Gitea Actions workflows that enable consistent CI/CD across all organization repositories, with automatic project type detection for Joomla extensions, Dolibarr modules, and generic applications. + +## Quick Start + +```yaml +# Basic quality check +jobs: + quality: + uses: MokoConsulting/moko-platform/.gitea/workflows/reusable-php-quality.yml@main + +# Type-aware build and release + build: + uses: MokoConsulting/moko-platform/.gitea/workflows/reusable-build.yml@main + + release: + uses: MokoConsulting/moko-platform/.gitea/workflows/reusable-release.yml@main + with: + version: '1.0.0' +``` + +## Workflow Categories + +### Quality & Testing Workflows +- **reusable-php-quality.yml** - PHP code quality analysis (PHPCS, PHPStan, Psalm) +- **reusable-joomla-testing.yml** - Joomla extension testing with matrix PHP/Joomla versions +- **reusable-ci-validation.yml** - Repository standards validation + +### Repository Maintenance Workflows +- **reusable-branch-cleanup.yml** - Automated cleanup of stale and merged branches + +### Type-Aware Orchestration Workflows +- **reusable-project-detector.yml** - Automatic project type detection +- **reusable-build.yml** - Universal build for all project types +- **reusable-release.yml** - Type-aware release creation and packaging +- **reusable-deploy.yml** - Multi-environment deployment + +> **Type-Aware Workflows** automatically detect whether your project is a Joomla extension, Dolibarr module, or generic application, and apply appropriate build/release/deploy steps. This enables a single workflow definition to work across all repositories. + +--- + +## Quality & Testing Workflows + +### PHP Quality Analysis + +Runs comprehensive PHP code quality checks using PHPCS, PHPStan, and Psalm with configurable standards and analysis levels. + +**Usage:** +```yaml +jobs: + quality: + uses: MokoConsulting/moko-platform/.gitea/workflows/reusable-php-quality.yml@main + with: + php-versions: '["8.1", "8.2"]' + tools: '["phpcs", "phpstan", "psalm"]' + phpcs-standard: 'PSR12' + phpstan-level: '6' +``` + +**Key Inputs:** +- `php-versions` (string) - JSON array of PHP versions, default: `["7.4", "8.0", "8.1", "8.2"]` +- `tools` (string) - JSON array of tools, default: `["phpcs", "phpstan", "psalm"]` +- `phpcs-standard` (string) - Coding standard, default: `PSR12` +- `phpstan-level` (string) - Analysis level 0-9, default: `5` +- `fail-on-error` (boolean) - Fail on errors, default: `true` + +**Outputs:** `quality-score` - Overall quality score percentage (0-100) + +### Joomla Testing + +Matrix testing for Joomla extensions across PHP and Joomla versions with PHPUnit, MySQL, and code coverage support. + +**Usage:** +```yaml +jobs: + test: + uses: MokoConsulting/moko-platform/.gitea/workflows/reusable-joomla-testing.yml@main + with: + php-versions: '["8.1", "8.2"]' + joomla-versions: '["4.4", "5.0", "5.1"]' + coverage: true + secrets: + CODECOV_TOKEN: ${{ secrets.CODECOV_TOKEN }} +``` + +**Key Inputs:** +- `php-versions` (string) - JSON array, default: `["7.4", "8.0", "8.1", "8.2"]` +- `joomla-versions` (string) - JSON array, default: `["4.4", "5.0", "5.1"]` +- `coverage` (boolean) - Enable coverage, default: `false` +- `run-integration-tests` (boolean) - Run integration tests, default: `true` + +> Automatically excludes incompatible combinations (e.g., PHP 7.4 + Joomla 5.x) + +### CI Validation + +Repository standards validation with configurable profiles (basic, full, strict). + +**Usage:** +```yaml +jobs: + validate: + uses: MokoConsulting/moko-platform/.gitea/workflows/reusable-ci-validation.yml@main + with: + profile: 'full' + validate-security: true +``` + +**Validation Profiles:** +- **basic** - Manifest, XML, PHP syntax, security checks +- **full** - Basic + changelog, license headers, language structure, paths, whitespace +- **strict** - Full validation with fail-on-warnings enabled + +**Key Inputs:** +- `profile` (string) - Validation profile, default: `basic` +- `validate-manifests` (boolean) - Validate XML manifests, default: `true` +- `validate-changelogs` (boolean) - Validate CHANGELOG.md, default: `true` +- `validate-licenses` (boolean) - Validate license headers, default: `true` +- `validate-security` (boolean) - Security checks, default: `true` +- `fail-on-warnings` (boolean) - Fail on warnings, default: `false` + +--- + +## Repository Maintenance Workflows + +### Branch Cleanup + +Automatically cleans up stale and merged branches with configurable exclusion patterns and dry-run support. + +**Usage:** +```yaml +jobs: + cleanup: + uses: MokoConsulting/moko-platform/.gitea/workflows/reusable-branch-cleanup.yml@main + with: + stale-days: 90 + delete-merged: true + delete-stale: true + dry-run: false + permissions: + contents: write +``` + +**Key Inputs:** +- `stale-days` (number) - Days before branch is stale, default: `90` +- `delete-merged` (boolean) - Delete merged branches, default: `true` +- `delete-stale` (boolean) - Delete stale branches, default: `true` +- `dry-run` (boolean) - Preview without deleting, default: `false` +- `exclude-patterns` (string) - JSON array of regex patterns to exclude, default: `["main", "master", "develop", "dev", "dev/.*", "rc/.*", "release/.*", "staging", "production"]` +- `exclude-prefix` (string) - Comma-separated prefixes to exclude, default: `"dependabot/,renovate/"` + +**Features:** +- Detects and deletes branches merged into default branch +- Identifies stale branches based on last commit date +- Configurable exclusion patterns (regex and prefix-based) +- Dry-run mode for previewing changes +- Detailed summary of deleted and failed branches + +**Example with custom exclusions:** +```yaml +jobs: + cleanup: + uses: MokoConsulting/moko-platform/.gitea/workflows/reusable-branch-cleanup.yml@main + with: + stale-days: 60 + delete-merged: true + delete-stale: true + dry-run: false + exclude-patterns: '["main", "master", "develop", "hotfix/.*"]' + exclude-prefix: 'dependabot/,renovate/,feature/' +``` + +--- + +## Type-Aware Orchestration Workflows + +### Project Type Detection + +Automatically detects project type and provides outputs for downstream workflows. + +**Usage:** +```yaml +jobs: + detect: + uses: MokoConsulting/moko-platform/.gitea/workflows/reusable-project-detector.yml@main +``` + +**Outputs:** +- `project-type` - Detected type: `joomla`, `dolibarr`, or `generic` +- `extension-type` - Extension type: `component`, `module`, `plugin`, `template`, `package`, or `application` +- `has-php` - Whether project contains PHP files (true/false) +- `has-node` - Whether project contains package.json (true/false) + +### Type-Aware Build + +Universal build workflow that adapts to project type with automatic dependency management. + +**Usage:** +```yaml +jobs: + build: + uses: MokoConsulting/moko-platform/.gitea/workflows/reusable-build.yml@main + with: + php-version: '8.1' + node-version: '20.x' + upload-artifacts: true +``` + +**Key Inputs:** +- `php-version` (string) - PHP version, default: `8.1` +- `node-version` (string) - Node.js version, default: `20.x` +- `upload-artifacts` (boolean) - Upload build artifacts, default: `true` +- `artifact-name` (string) - Artifact name, default: `build-artifacts` + +**Build Logic:** +- **Joomla:** Installs dependencies, runs npm build if available, prepares extension +- **Dolibarr:** Installs production dependencies, runs build scripts +- **Generic:** Runs npm build, checks for Makefile, executes build commands + +### Type-Aware Release + +Creates releases with type-specific packaging and marketplace support. + +**Usage:** +```yaml +jobs: + release: + uses: MokoConsulting/moko-platform/.gitea/workflows/reusable-release.yml@main + with: + version: '1.0.0' + prerelease: false + create-github-release: true + permissions: + contents: write +``` + +**Key Inputs:** +- `version` (string, **required**) - Release version in semver format +- `prerelease` (boolean) - Mark as pre-release, default: `false` +- `draft` (boolean) - Create as draft, default: `false` +- `create-github-release` (boolean) - Create GitHub release, default: `true` +- `publish-to-marketplace` (boolean) - Publish to marketplace, default: `false` + +**Package Creation:** +- **Joomla/Dolibarr:** ZIP package with manifest version updates +- **Generic:** TAR.GZ package with build artifacts +- All packages include SHA256 and MD5 checksums + +### Type-Aware Deployment + +Multi-environment deployment with type-specific logic and health checks. + +**Usage:** +```yaml +jobs: + deploy: + uses: MokoConsulting/moko-platform/.gitea/workflows/reusable-deploy.yml@main + with: + environment: staging + deployment-method: rsync + health-check-url: https://staging.example.com/health + secrets: + DEPLOY_HOST: ${{ secrets.STAGING_HOST }} + DEPLOY_USER: ${{ secrets.STAGING_USER }} + DEPLOY_KEY: ${{ secrets.STAGING_SSH_KEY }} + DEPLOY_PATH: ${{ secrets.STAGING_PATH }} + permissions: + contents: read + deployments: write +``` + +**Key Inputs:** +- `environment` (string, **required**) - Target: `staging` or `production` +- `deployment-method` (string) - Method: `rsync`, `ssh`, `ftp`, `kubernetes`, `custom`, default: `custom` +- `health-check-url` (string) - URL for post-deployment health check +- `health-check-timeout` (number) - Timeout in seconds, default: `300` + +**Deployment Methods:** +- **rsync:** Direct sync to remote server +- **ssh:** Package transfer and extraction via SSH +- **custom:** Type-specific deployment logic (Joomla extension, Dolibarr module, generic app) + +--- + +## Complete Pipeline Examples + +### Example 1: Type-Aware CI/CD Pipeline + +Single pipeline that works for Joomla, Dolibarr, and generic projects: + +```yaml +name: CI/CD Pipeline + +on: + push: + branches: [main, staging, dev/**] + pull_request: + branches: [main] + release: + types: [published] + +permissions: + contents: write + deployments: write + pull-requests: write + checks: write + +jobs: + # Auto-detect project type + detect: + uses: MokoConsulting/moko-platform/.gitea/workflows/reusable-project-detector.yml@main + + # Validate code + validate: + uses: MokoConsulting/moko-platform/.gitea/workflows/reusable-ci-validation.yml@main + with: + profile: 'full' + + # Check quality (PHP projects only) + quality: + needs: detect + if: needs.detect.outputs.has-php == 'true' + uses: MokoConsulting/moko-platform/.gitea/workflows/reusable-php-quality.yml@main + with: + php-versions: '["8.1", "8.2"]' + + # Test Joomla extensions + test: + needs: [detect, quality] + if: needs.detect.outputs.project-type == 'joomla' + uses: MokoConsulting/moko-platform/.gitea/workflows/reusable-joomla-testing.yml@main + with: + php-versions: '["8.1", "8.2"]' + coverage: true + secrets: + CODECOV_TOKEN: ${{ secrets.CODECOV_TOKEN }} + + # Build (works for all types) + build: + needs: [detect, validate] + uses: MokoConsulting/moko-platform/.gitea/workflows/reusable-build.yml@main + + # Deploy to staging + deploy-staging: + needs: build + if: github.ref == 'refs/heads/staging' + uses: MokoConsulting/moko-platform/.gitea/workflows/reusable-deploy.yml@main + with: + environment: staging + deployment-method: rsync + secrets: inherit + + # Create release on tag + release: + needs: [detect, build] + if: startsWith(github.ref, 'refs/tags/v') + uses: MokoConsulting/moko-platform/.gitea/workflows/reusable-release.yml@main + with: + version: ${{ github.ref_name }} + + # Deploy to production + deploy-production: + needs: release + if: github.event_name == 'release' + uses: MokoConsulting/moko-platform/.gitea/workflows/reusable-deploy.yml@main + with: + environment: production + version: ${{ github.event.release.tag_name }} + secrets: inherit +``` + +### Example 2: Basic Quality and Testing + +Simple quality and testing pipeline: + +```yaml +name: Quality & Test + +on: [push, pull_request] + +jobs: + validate: + uses: MokoConsulting/moko-platform/.gitea/workflows/reusable-ci-validation.yml@main + with: + profile: 'full' + + quality: + needs: validate + uses: MokoConsulting/moko-platform/.gitea/workflows/reusable-php-quality.yml@main + with: + php-versions: '["8.1", "8.2"]' + + test: + needs: quality + uses: MokoConsulting/moko-platform/.gitea/workflows/reusable-joomla-testing.yml@main + with: + coverage: true + secrets: + CODECOV_TOKEN: ${{ secrets.CODECOV_TOKEN }} +``` + +--- + +## Best Practices + +### Version Pinning + +**Recommended:** Pin to main branch for automatic updates +```yaml +uses: MokoConsulting/moko-platform/.gitea/workflows/reusable-php-quality.yml@main +``` + +**Stable:** Pin to specific tag +```yaml +uses: MokoConsulting/moko-platform/.gitea/workflows/reusable-php-quality.yml@v1.0.0 +``` + +**Maximum Stability:** Pin to commit SHA +```yaml +uses: MokoConsulting/moko-platform/.gitea/workflows/reusable-php-quality.yml@abc1234 +``` + +### Secret Management + +**Pass all secrets:** +```yaml +secrets: inherit +``` + +**Pass specific secrets:** +```yaml +secrets: + CODECOV_TOKEN: ${{ secrets.CODECOV_TOKEN }} + DEPLOY_KEY: ${{ secrets.DEPLOY_KEY }} +``` + +### Progressive Adoption + +Start with basic validation, gradually increase strictness: + +```yaml +jobs: + # Dev branches: basic validation + validate-dev: + if: startsWith(github.ref, 'refs/heads/dev/') + uses: MokoConsulting/moko-platform/.gitea/workflows/reusable-ci-validation.yml@main + with: + profile: 'basic' + + # Main branch: strict validation + validate-main: + if: github.ref == 'refs/heads/main' + uses: MokoConsulting/moko-platform/.gitea/workflows/reusable-ci-validation.yml@main + with: + profile: 'strict' + fail-on-warnings: true +``` + +--- + +## Troubleshooting + +### Workflow Not Found +**Error:** `Unable to resolve action MokoConsulting/moko-platform/.gitea/workflows/...` + +**Solution:** Ensure calling repository has access to moko-platform. For private repositories, configure proper access permissions. + +### Missing Secrets +**Error:** `Secret CODECOV_TOKEN is not available` + +**Solution:** Add secret at organization or repository level, or pass explicitly: +```yaml +secrets: + CODECOV_TOKEN: ${{ secrets.CODECOV_TOKEN }} +``` + +### Matrix Job Failures +Random matrix job failures may indicate rate limiting or resource contention. + +**Solution:** Reduce concurrency +```yaml +strategy: + matrix: + php: ['8.1', '8.2'] + max-parallel: 2 # Limit concurrent jobs +``` + +### Health Check Timeout +**Solution:** Increase timeout or verify URL accessibility +```yaml +with: + health-check-timeout: 600 # 10 minutes +``` + +--- + +## Migration from Local Workflows + +**Steps:** +1. Identify workflow type (quality, testing, validation, build, release, deploy) +2. Map your inputs to reusable workflow parameters +3. Update workflow file to call reusable workflow +4. Test on development branch +5. Archive old workflow once validated + +**Example Migration:** + +```yaml +# Before: Local workflow +jobs: + phpcs: + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v4 + - uses: shivammathur/setup-php@v2 + - run: phpcs --standard=PSR12 src/ + +# After: Reusable workflow +jobs: + quality: + uses: MokoConsulting/moko-platform/.gitea/workflows/reusable-php-quality.yml@main + with: + phpcs-standard: 'PSR12' + tools: '["phpcs"]' +``` + +--- + +## Support & Resources + +**Support:** +- Documentation: [CI Migration Guide](CI_MIGRATION_GUIDE) +- Issues: Open issue in moko-platform repository +- Slack: #devops-support channel + +**Related Documentation:** +- [CI Migration Guide](CI_MIGRATION_GUIDE) - Detailed migration strategy +- [GitHub Reusing Workflows](https://docs.github.com/en/actions/using-workflows/reusing-workflows) +- [Workflow Templates](../../templates/workflows/) - Additional templates + +--- + +## Version History + +| Version | Date | Changes | +|---------|------|---------| +| 02.01.00 | 2026-01-11 | Added reusable-branch-cleanup workflow, standards-compliance workflow | +| 02.00.00 | 2026-01-09 | Consolidated documentation, added type-aware workflows | | 01.00.00 | 2026-01-09 | Initial release (php-quality, joomla-testing, ci-validation) | +--- + +*Repo: [moko-platform](https://git.mokoconsulting.tech/MokoConsulting/moko-platform) · [moko-platform wiki](https://git.mokoconsulting.tech/MokoConsulting/moko-platform/wiki/Home)* + +| Field | Value | +|---|---| +| Minimum Version | 04.07.00 | +| Platform | all | +| Applies To | All repositories | + +| Revision | Date | Author | Description | +|---|---|---|---| +| 1.0 | 2026-05-08 | Moko Consulting | Initial version | diff --git a/moko-platform/workflows-rs-deployment.-.-.md b/moko-platform/workflows-rs-deployment.-.-.md index 81c42ed..619a088 100644 --- a/moko-platform/workflows-rs-deployment.-.-.md +++ b/moko-platform/workflows-rs-deployment.-.-.md @@ -1,29 +1,42 @@ ← [Home](Home) -[![moko-platform](https://img.shields.io/badge/moko-platform-05.00.00-orange)](https://git.mokoconsulting.tech/MokoConsulting/moko-platform) - -# Release Staging (RS) Server Deployment - -> **DEPRECATED (v05.00.00):** The `deploy-rs.yml` workflow has been **retired**. RS deployment is now handled exclusively through the release pipeline. Release artifacts are published via GitHub Releases (`auto-release.yml`) and distributed through platform-specific channels (Joomla `updates.xml`, Dolibarr `update.txt`). The `RS_FTP_*` variables and secrets are no longer used. - -## Current Release Pipeline - -``` -dev → [alpha] → [beta] → rc → version/XX → main → dev - optional optional -``` - -Production/RS deployment is achieved by: - -1. **Joomla** — GitHub Release ZIP + SHA-256 + `updates.xml` with 5 stability entries (`development`, `alpha`, `beta`, `release-candidate`, `vXX`) -2. **Dolibarr** — GitHub Release + `update.txt` -3. **Generic** — GitHub Release - -There is no longer a separate SFTP deployment step to a release staging server. - -## See Also - -- [Dev Deployment](dev-deployment.md) — development server (still active) -- [Demo Deployment](demo-deployment.md) — demo server (still active) -- [Auto Release](auto-release.md) — release pipeline that replaced RS deployment +[![moko-platform](https://img.shields.io/badge/moko-platform-04.06.00-orange)](https://git.mokoconsulting.tech/MokoConsulting/moko-platform) + +# Release Staging (RS) Server Deployment + +> **DEPRECATED (v04.06.00):** The `deploy-rs.yml` workflow has been **retired**. RS deployment is now handled exclusively through the release pipeline. Release artifacts are published via GitHub Releases (`auto-release.yml`) and distributed through platform-specific channels (Joomla `updates.xml`, Dolibarr `update.txt`). The `RS_FTP_*` variables and secrets are no longer used. + +## Current Release Pipeline + +``` +dev → [alpha] → [beta] → rc → version/XX → main → dev + optional optional +``` + +Production/RS deployment is achieved by: + +1. **Joomla** — GitHub Release ZIP + SHA-256 + `updates.xml` with 5 stability entries (`development`, `alpha`, `beta`, `release-candidate`, `vXX`) +2. **Dolibarr** — GitHub Release + `update.txt` +3. **Generic** — GitHub Release + +There is no longer a separate SFTP deployment step to a release staging server. + +## See Also + +- [Dev Deployment](dev-deployment.md) — development server (still active) +- [Demo Deployment](demo-deployment.md) — demo server (still active) +- [Auto Release](auto-release.md) — release pipeline that replaced RS deployment - [Release System](release-system.md) — end-to-end release lifecycle +--- + +*Repo: [moko-platform](https://git.mokoconsulting.tech/MokoConsulting/moko-platform) · [moko-platform wiki](https://git.mokoconsulting.tech/MokoConsulting/moko-platform/wiki/Home)* + +| Field | Value | +|---|---| +| Minimum Version | 04.07.00 | +| Platform | all | +| Applies To | All repositories | + +| Revision | Date | Author | Description | +|---|---|---|---| +| 1.0 | 2026-05-08 | Moko Consulting | Initial version | diff --git a/moko-platform/workflows-secret-scanning.-.-.md b/moko-platform/workflows-secret-scanning.-.-.md index 5ea40d6..cbca9fb 100644 --- a/moko-platform/workflows-secret-scanning.-.-.md +++ b/moko-platform/workflows-secret-scanning.-.-.md @@ -1,61 +1,74 @@ ← [Home](Home) -[![moko-platform](https://img.shields.io/badge/moko-platform-05.00.00-orange)](https://git.mokoconsulting.tech/MokoConsulting/moko-platform) - -# Secret Scanning (Gitleaks) - -**Status**: ✅ Active | **Version**: 01.00.00 | **Last Updated**: 2026-05-07 - -## Overview - -Scans repositories for leaked secrets (API keys, tokens, passwords, private keys) using [Gitleaks](https://github.com/gitleaks/gitleaks). Deployed to all governed repositories. - -## Triggers - -| Trigger | Scope | -|---------|-------| -| PR to main/dev/** | Scans PR commits only (incremental) | -| Weekly Monday 05:00 UTC | Full repository history scan | -| Manual dispatch | Full scan | - -## What It Detects - -- API keys and tokens (AWS, GCP, Azure, GitHub, Gitea, etc.) -- Private keys (RSA, SSH, PGP) -- Database connection strings -- OAuth client secrets -- JWT tokens -- Generic high-entropy strings - -## Notifications - -Findings trigger an **urgent** ntfy alert to the `gitea-security` topic with instructions to rotate credentials immediately. - -## Configuration - -The workflow uses Gitleaks' built-in rules. To add custom rules or allowlists, create a `.gitleaks.toml` in the repo root. - -### Allowlisting False Positives - -```toml -# .gitleaks.toml -[allowlist] - paths = [ - '''vendor/''', - '''node_modules/''' - ] - commits = [ - "abc123..." - ] -``` - -## Related Documentation - -- [Security Audit (Dependencies)](security-audit) -- [Branch Protection](branch-protection) - -## Changelog - -| Version | Date | Changes | -|---------|------|---------| +[![moko-platform](https://img.shields.io/badge/moko-platform-04.06.00-orange)](https://git.mokoconsulting.tech/MokoConsulting/moko-platform) + +# Secret Scanning (Gitleaks) + +**Status**: ✅ Active | **Version**: 01.00.00 | **Last Updated**: 2026-05-07 + +## Overview + +Scans repositories for leaked secrets (API keys, tokens, passwords, private keys) using [Gitleaks](https://github.com/gitleaks/gitleaks). Deployed to all governed repositories. + +## Triggers + +| Trigger | Scope | +|---------|-------| +| PR to main/dev/** | Scans PR commits only (incremental) | +| Weekly Monday 05:00 UTC | Full repository history scan | +| Manual dispatch | Full scan | + +## What It Detects + +- API keys and tokens (AWS, GCP, Azure, GitHub, Gitea, etc.) +- Private keys (RSA, SSH, PGP) +- Database connection strings +- OAuth client secrets +- JWT tokens +- Generic high-entropy strings + +## Notifications + +Findings trigger an **urgent** ntfy alert to the `gitea-security` topic with instructions to rotate credentials immediately. + +## Configuration + +The workflow uses Gitleaks' built-in rules. To add custom rules or allowlists, create a `.gitleaks.toml` in the repo root. + +### Allowlisting False Positives + +```toml +# .gitleaks.toml +[allowlist] + paths = [ + '''vendor/''', + '''node_modules/''' + ] + commits = [ + "abc123..." + ] +``` + +## Related Documentation + +- [Security Audit (Dependencies)](security-audit) +- [Branch Protection](branch-protection) + +## Changelog + +| Version | Date | Changes | +|---------|------|---------| | 01.00.00 | 2026-05-07 | Initial release | +--- + +*Repo: [moko-platform](https://git.mokoconsulting.tech/MokoConsulting/moko-platform) · [moko-platform wiki](https://git.mokoconsulting.tech/MokoConsulting/moko-platform/wiki/Home)* + +| Field | Value | +|---|---| +| Minimum Version | 04.07.00 | +| Platform | all | +| Applies To | All repositories | + +| Revision | Date | Author | Description | +|---|---|---|---| +| 1.0 | 2026-05-08 | Moko Consulting | Initial version | diff --git a/moko-platform/workflows-shared-workflows.-.-.md b/moko-platform/workflows-shared-workflows.-.-.md index d3bcb28..382d9a4 100644 --- a/moko-platform/workflows-shared-workflows.-.-.md +++ b/moko-platform/workflows-shared-workflows.-.-.md @@ -1,6 +1,6 @@ ← [Home](Home) -[![moko-platform](https://img.shields.io/badge/moko-platform-05.00.00-orange)](https://git.mokoconsulting.tech/MokoConsulting/moko-platform) +[![moko-platform](https://img.shields.io/badge/moko-platform-04.06.00-orange)](https://git.mokoconsulting.tech/MokoConsulting/moko-platform) # Shared Workflow Templates @@ -90,7 +90,7 @@ See dedicated docs: - [Dev Deployment](dev-deployment.md) — development server - [Demo Deployment](demo-deployment.md) — demo server -> **Note:** `deploy-rs.yml` has been **retired** (v05.00.00). RS deployment is now via the release pipeline only. See [RS Deployment (deprecated)](rs-deployment.md). +> **Note:** `deploy-rs.yml` has been **retired** (v04.06.00). RS deployment is now via the release pipeline only. See [RS Deployment (deprecated)](rs-deployment.md). ### Common Features (both deploy workflows) @@ -223,3 +223,16 @@ Every governed repo has a `.gitea/workflows/custom/` directory that is **never t On every sync, the `RepositorySynchronizer` checks if the remote `composer.json` requires `mokoconsulting-tech/enterprise`. If missing or stale (`dev-main`), it adds/updates it to `"dev-version/XX"` — always pinned to the current version branch, never bleeding-edge main. Governed repos can manually override to `dev-main` for bleeding-edge testing, but this will be corrected on the next sync. +--- + +*Repo: [moko-platform](https://git.mokoconsulting.tech/MokoConsulting/moko-platform) · [moko-platform wiki](https://git.mokoconsulting.tech/MokoConsulting/moko-platform/wiki/Home)* + +| Field | Value | +|---|---| +| Minimum Version | 04.07.00 | +| Platform | all | +| Applies To | All repositories | + +| Revision | Date | Author | Description | +|---|---|---|---| +| 1.0 | 2026-05-08 | Moko Consulting | Initial version | diff --git a/moko-platform/workflows-standards-compliance.-.-.md b/moko-platform/workflows-standards-compliance.-.-.md index 9363902..dc2a896 100644 --- a/moko-platform/workflows-standards-compliance.-.-.md +++ b/moko-platform/workflows-standards-compliance.-.-.md @@ -1,590 +1,603 @@ ← [Home](Home) -[![moko-platform](https://img.shields.io/badge/moko-platform-05.00.00-orange)](https://git.mokoconsulting.tech/MokoConsulting/moko-platform) - -# Standards Compliance Workflow - -**Workflow**: `standards-compliance.yml` -**Status**: Active | **Version**: 04.00.04 | **Last Updated**: 2026-02-21 - -## Overview - -The Standards Compliance workflow is a comprehensive validation system that ensures repositories meet moko-platform requirements across multiple dimensions including structure, documentation quality, coding standards, security, and maintainability. - -## Purpose - -- **Enforce Standards**: Automatically validate compliance with moko-platform policies -- **Quality Assurance**: Ensure consistent quality across all organization repositories -- **Early Detection**: Catch compliance issues before merge -- **Actionable Feedback**: Provide clear remediation steps for any violations -- **Comprehensive Reporting**: Generate detailed compliance reports with scores - -## Workflow Triggers - -```yaml -on: - push: - branches: - - main - - dev/** - - rc/** - pull_request: - branches: - - main - - dev/** - - rc/** - workflow_dispatch: -``` - -**Runs on**: -- Every push to main, dev/*, or rc/* branches -- Every pull request targeting main, dev/*, or rc/* -- Manual trigger via Gitea Actions UI - -## Validation Areas - -The workflow performs 10 comprehensive validation checks organized into two categories: - -### Critical Checks (Must Pass) - -These checks are **blocking** - the workflow will fail if any critical check fails: - -| Check | Description | Validator | Priority | -|-------|-------------|-----------|----------| -| 📁 **Repository Structure** | Validates required directories and files exist | Built-in shell | 🔴 Critical | -| 📚 **Documentation Quality** | Analyzes README, checks documentation completeness | Built-in shell | 🔴 Critical | -| 💻 **Coding Standards** | Runs language-specific linters (Python, PHP, YAML) | yamllint, black, pylint, phpcs | 🔴 Critical | -| ⚖️ **License Compliance** | Validates license file and SPDX identifiers | Built-in shell | 🔴 Critical | -| 🧹 **Git Repository Hygiene** | Checks commit messages, branch naming, .gitignore | Built-in shell | 🔴 Critical | -| ⚙️ **Workflow Configuration** | Validates Gitea Actions workflow files | actionlint, custom checks | 🔴 Critical | -| 🔢 **Version Consistency** | Ensures all version numbers match across repository | check_version_consistency.php | 🔴 Critical | -| 🔐 **Script Integrity** | Validates SHA-256 hashes of critical scripts | validate_script_registry.py | 🔴 Critical | - -### Informational Checks (Non-Blocking) - -These checks provide **recommendations** but don't fail the workflow: - -| Check | Description | Validator | Priority | -|-------|-------------|-----------|----------| -| 🏢 **Enterprise Readiness** | Assesses enterprise-grade features and patterns | check_enterprise_readiness.php | ℹ️ Info | -| 🏥 **Repository Health** | Evaluates overall repository quality metrics | check_repo_health.php | ℹ️ Info | - -## Detailed Check Descriptions - -### 1. Repository Structure Validation - -**What it checks**: -- Required directories: `docs/`, `scripts/`, `.github/` -- Required files: `README.md`, `LICENSE`, `CONTRIBUTING.md`, `SECURITY.md`, `CHANGELOG.md`, `.editorconfig` -- File size and completeness validation - -**Compliance Requirements**: -- All required directories must exist -- All required files must be present -- README must be at least 500 bytes -- LICENSE must be at least 100 bytes - -**Remediation**: -```bash -# Create missing directories -mkdir -p docs scripts .gitea/workflows - -# Create required files from templates -cp templates/docs/required/README.md ./ -cp templates/docs/required/CONTRIBUTING.md ./ -cp templates/docs/required/SECURITY.md ./ -``` - -### 2. Documentation Quality Check - -**What it checks**: -- README.md metrics (size, lines, words, headings, links, code blocks) -- Documentation completeness -- Content quality indicators - -**Compliance Requirements**: -- README minimum 500 bytes, 20 lines, 100 words -- At least 3 headings for structure -- Include links and code examples - -**Scoring**: -- Size: 500+ bytes (good), <500 (warning), >50KB (warning - too long) -- Headings: 3+ (good), <3 (warning) -- Links: 1+ (good), 0 (info - consider adding) -- Code blocks: 1+ (good), 0 (info - consider adding) - -### 3. Coding Standards Validation - -**What it checks**: -- YAML files: Validates syntax and formatting with `yamllint` -- Python files: Code formatting with `black`, linting with `pylint` -- PHP files: Coding standards with `phpcs` (PSR-12) - -**Compliance Requirements**: -- All YAML files must be valid and properly formatted -- Python code must follow Black formatting -- PHP code must follow PSR-12 standards - -**Remediation**: -```bash -# Fix YAML formatting -yamllint --format auto .gitea/workflows/*.yml - -# Fix Python formatting -black scripts/**/*.py - -# Fix PHP code style -phpcs --standard=PSR12 src/ -``` - -### 4. License Compliance - -**What it checks**: -- LICENSE file exists -- File headers contain copyright and SPDX identifiers -- Consistent licensing across repository - -**Compliance Requirements**: -- LICENSE file present at repository root -- All source files include copyright header -- SPDX-License-Identifier present in headers - -**Example Header**: -```php - -// SPDX-License-Identifier: GPL-3.0-or-later -``` - -### 5. Git Repository Hygiene - -**What it checks**: -- Commit message format -- Branch naming conventions -- .gitignore completeness -- No sensitive files in repository - -**Compliance Requirements**: -- Conventional commit messages -- Branch names follow pattern: `feature/*`, `bugfix/*`, `hotfix/*`, `release/*` -- Comprehensive .gitignore file - -### 6. Workflow Configuration Validation - -**What it checks**: -- Valid YAML syntax in workflow files -- Required workflows present -- CodeQL configuration if applicable -- Action version pinning for security - -**Compliance Requirements**: -- All workflows have valid YAML syntax -- Actions pinned to commit hashes for security -- Proper permissions configured - -### 7. Version Consistency Check ⭐ NEW - -**What it checks**: -- All version references match the canonical version in `composer.json` -- Checks 39+ files including: - - Documentation (README.md, CHANGELOG.md, CONTRIBUTING.md) - - Workflows (.gitea/workflows/*.yml) - - PHP source files (src/**/*.php) - - Configuration files - -**Compliance Requirements**: -- Single source of truth: version in `composer.json` -- All references must match exactly -- No version drift across repository - -**Validator**: `api/validate/check_version_consistency.php` - -**Remediation**: -```bash -# Check current status -php api/validate/check_version_consistency.php --verbose - -# Update all version references (if mismatches found) -# Manually update files or use bulk search/replace -``` - -### 8. Script Integrity Validation ⭐ NEW - -**What it checks**: -- SHA-256 hashes of critical scripts match registry -- No unauthorized modifications to security-critical scripts -- Registry file (scripts/.script-registry.json) is up-to-date - -**Compliance Requirements**: -- All scripts in registry must have valid SHA-256 hashes -- Critical priority scripts cannot have mismatches -- Changes to scripts must update registry - -**Validator**: `api/maintenance/validate_script_registry.py` - -**Remediation**: -```bash -# Validate current hashes -python3 api/maintenance/validate_script_registry.py --priority critical - -# Update registry after legitimate changes -python3 api/maintenance/generate_script_registry.py --update - -# Or use auto-update workflow -# .gitea/workflows/auto-update-sha.yml -``` - -### 9. Enterprise Readiness Check ⭐ NEW (Informational) - -**What it checks**: -- Enterprise-grade features implementation -- Security best practices -- Scalability patterns -- Error handling and logging -- Transaction management -- API design patterns - -**Assessment Areas**: -- Architecture patterns -- Error recovery mechanisms -- Monitoring and observability -- Documentation completeness -- Test coverage -- Security controls - -**Validator**: `api/validate/check_enterprise_readiness.php` - -**Note**: This check is **informational only** and does not block merges. It provides recommendations for improving enterprise readiness. - -### 10. Repository Health Check ⭐ NEW (Informational) - -**What it checks**: -- Code quality metrics -- Technical debt indicators -- Dependency health -- Documentation coverage -- Test coverage -- Issue/PR activity - -**Health Metrics**: -- File structure organization -- Code duplication -- Dependency freshness -- Security vulnerabilities -- Community engagement - -**Validator**: `api/validate/check_repo_health.php` - -**Note**: This check is **informational only** and does not block merges. It provides insights for continuous improvement. - -## Compliance Scoring - -The workflow calculates a compliance percentage based on critical checks: - -``` -Compliance % = (Critical Checks Passed / Total Critical Checks) × 100 -``` - -### Score Interpretation - -| Score | Status | Description | -|-------|--------|-------------| -| 100% | ✅ **COMPLIANT** | All critical checks passed - repository fully compliant | -| 80-99% | ⚠️ **MOSTLY COMPLIANT** | Most checks passed - minor issues to address | -| 50-79% | ⚠️ **PARTIALLY COMPLIANT** | Significant issues - requires attention | -| 0-49% | ❌ **NON-COMPLIANT** | Major compliance violations - immediate action required | - -### Example Output - -``` -## ✅ Overall Status: COMPLIANT (100%) - -**Critical Checks:** 8/8 passed -**Total Checks:** 10/10 passed -**Informational:** 0 warning(s) - -████████████████████ 100% - -## Validation Results - -| Area | Status | Result | Priority | -|-----------------------------|---------|------------|-------------| -| 📁 Repository Structure | ✅ Pass | Compliant | - | -| 📚 Documentation Quality | ✅ Pass | Compliant | - | -| 💻 Coding Standards | ✅ Pass | Compliant | - | -| ⚖️ License Compliance | ✅ Pass | Compliant | - | -| 🧹 Git Repository Hygiene | ✅ Pass | Compliant | - | -| ⚙️ Workflow Configuration | ✅ Pass | Compliant | - | -| 🔢 Version Consistency | ✅ Pass | All versions match | - | -| 🔐 Script Integrity | ✅ Pass | SHA hashes validated | - | -| 🏢 Enterprise Readiness | ✅ Pass | Ready for enterprise | ℹ️ Info | -| 🏥 Repository Health | ✅ Pass | Health check passed | ℹ️ Info | -``` - -## Usage Examples - -### Running Manually - -```bash -# Trigger workflow manually via Gitea Actions UI -# Go to: Actions → Standards Compliance → Run workflow - -# Or use GitHub CLI -gh workflow run standards-compliance.yml -``` - -### Local Validation - -Run individual validators locally before pushing: - -```bash -# Check version consistency -php api/validate/check_version_consistency.php --verbose - -# Validate script integrity -python3 api/maintenance/validate_script_registry.py --priority critical --verbose - -# Check enterprise readiness -php api/validate/check_enterprise_readiness.php --verbose - -# Check repository health -php api/validate/check_repo_health.php --verbose - -# Lint YAML files -yamllint .gitea/workflows/*.yml - -# Format Python code -black --check scripts/**/*.py - -# Check PHP code style -phpcs --standard=PSR12 src/ -``` - -### Fixing Common Issues - -#### Version Mismatches - -```bash -# 1. Identify current version -grep '"version"' composer.json - -# 2. Find mismatches -php api/validate/check_version_consistency.php - -# 3. Update all references to match -# Use sed or manually update files listed in output -``` - -#### Script Integrity Violations - -```bash -# If changes are legitimate: -python3 api/maintenance/generate_script_registry.py --update - -# If changes are NOT authorized: -git checkout HEAD -- scripts/ -``` - -#### Coding Standard Violations - -```bash -# Auto-fix Python formatting -black scripts/**/*.py - -# Auto-fix PHP code style -phpcbf --standard=PSR12 src/ - -# Fix YAML issues -# Manual fixes required based on yamllint output -``` - -## Integration with Pull Requests - -The workflow automatically: - -1. **Runs on every PR** to main, dev/*, or rc/* branches -2. **Posts results** in the PR checks section -3. **Provides detailed summary** in the workflow run -4. **Blocks merge** if critical checks fail -5. **Offers remediation steps** for any violations - -### PR Status Checks - -| Check Result | PR Status | Merge Allowed | -|--------------|-----------|---------------| -| All critical checks pass | ✅ Success | Yes | -| Any critical check fails | ❌ Failure | No (blocked) | -| Only informational warnings | ✅ Success | Yes | - -## Workflow Architecture - -``` -┌─────────────────────────────────────────────────────────────┐ -│ PARALLEL VALIDATION CHECKS │ -└─────────────────────────────────────────────────────────────┘ - │ - ├─────────────┬──────────────┬──────────────┬────────────┐ - ▼ ▼ ▼ ▼ ▼ -┌─────────┐ ┌──────────┐ ┌──────────┐ ┌─────────┐ ┌──────────┐ -│Repository │File Header │Code Style│ │ Docs │ │ License │ -│Structure│ │ Validation│ │ Check │ │ Check │ │ Check │ -└─────────┘ └──────────┘ └──────────┘ └─────────┘ └──────────┘ - │ │ │ │ │ - ├─────────────┼──────────────┼──────────────┼────────────┤ - ▼ ▼ ▼ ▼ ▼ -┌─────────┐ ┌──────────┐ ┌──────────┐ ┌─────────┐ ┌──────────┐ -│ Git │ │ Workflow │ │ Version │ │ Script │ │Enterprise│ -│ Hygiene │ │ Config │ │Consistency│ │Integrity│ │Readiness │ -└─────────┘ └──────────┘ └──────────┘ └─────────┘ └──────────┘ - │ │ │ │ │ - └─────────────┴──────────────┴──────────────┴────────────┘ - │ - ▼ - ┌──────────────────┐ - │ All Checks Pass?│ - └──────────────────┘ - │ │ - YES │ │ NO - ▼ ▼ - ┌──────────┐ ┌──────────────┐ - │ SUCCESS │ │ CREATE ISSUE │ - │ Summary │ │ with Failure │ - └──────────┘ │ Details │ - └──────────────┘ -``` - -## Customization - -### Adjusting Severity - -To change a critical check to informational (non-blocking): - -```yaml -# In the summary job, change from: -[ "$CHECK_STATUS" = "success" ] && PASSED=$((PASSED + 1)) || FAILED=$((FAILED + 1)) - -# To: -if [ "$CHECK_STATUS" = "success" ]; then - PASSED=$((PASSED + 1)) -else - WARNINGS=$((WARNINGS + 1)) -fi -``` - -### Adding Custom Checks - -Add a new validation job: - -```yaml -custom-check: - name: Custom Validation - runs-on: ubuntu-latest - steps: - - name: Checkout - uses: actions/checkout@v6 - - - name: Run Custom Validator - run: | - ./scripts/custom-validator.sh -``` - -Then add it to the summary `needs` array. - -### Skipping Checks - -To skip a check temporarily, add to job: - -```yaml -if: false # Skip this check -``` - -Or make conditional: - -```yaml -if: ${{ github.event_name != 'pull_request' }} # Skip on PRs -``` - -## Troubleshooting - -### Workflow Fails Unexpectedly - -**Check**: -1. Review workflow run logs in Gitea Actions -2. Look for specific error messages in failed jobs -3. Check if required scripts exist (new checks depend on PHP/Python scripts) - -**Common Issues**: -- Missing validator scripts (version/enterprise/health checks) -- PHP/Python not available in runner -- Permissions issues with files - -### Version Consistency Always Fails - -**Cause**: Multiple version references across repository don't match - -**Fix**: -1. Identify canonical version: `grep '"version"' composer.json` -2. Find mismatches: `php api/validate/check_version_consistency.php` -3. Update all references to match canonical version - -### Script Integrity Violations - -**Legitimate Changes**: -```bash -# Update registry after modifying scripts -python3 api/maintenance/generate_script_registry.py --update -git add scripts/.script-registry.json -git commit -m "chore: update script registry" -``` - -**Unauthorized Changes**: -```bash -# Restore original scripts -git checkout HEAD -- scripts/ -``` - -## Related Documentation - -- [Workflow Architecture](workflow-architecture) -- [Workflow Inventory](workflow-inventory) -- [Repository Structure Standards](policy-core-structure) -- [Coding Style Guide](policy-coding-style-guide) -- [File Header Standards](policy-file-header-standards) -- [License Compliance Policy](policy-license-compliance) -- [Version Management](guide-version-badge-guide) -- [Script Integrity Guide](guide-script-integrity-validation) - -## Changelog - -### v04.00.04 (2026-02-21) - -**Added**: -- ✨ Version Consistency Check - Validates all version numbers match -- ✨ Script Integrity Validation - Verifies SHA-256 hashes -- ✨ Enterprise Readiness Check - Assesses enterprise patterns (informational) -- ✨ Repository Health Check - Evaluates overall quality (informational) - -**Changed**: -- 📊 Enhanced compliance scoring with critical vs informational distinction -- 📊 Improved summary reporting with detailed breakdowns -- 📊 Total validation checks increased from 6 to 10 - -**Fixed**: -- 🐛 Compliance percentage now correctly calculates based on critical checks only - -### v04.00.04 (2026-01-07) - -**Added**: -- Initial comprehensive standards compliance workflow -- Repository structure validation -- Documentation quality checks -- Coding standards enforcement -- License compliance validation -- Git hygiene checks -- Workflow configuration validation - +[![moko-platform](https://img.shields.io/badge/moko-platform-04.06.00-orange)](https://git.mokoconsulting.tech/MokoConsulting/moko-platform) + +# Standards Compliance Workflow + +**Workflow**: `standards-compliance.yml` +**Status**: Active | **Version**: 04.00.04 | **Last Updated**: 2026-02-21 + +## Overview + +The Standards Compliance workflow is a comprehensive validation system that ensures repositories meet moko-platform requirements across multiple dimensions including structure, documentation quality, coding standards, security, and maintainability. + +## Purpose + +- **Enforce Standards**: Automatically validate compliance with moko-platform policies +- **Quality Assurance**: Ensure consistent quality across all organization repositories +- **Early Detection**: Catch compliance issues before merge +- **Actionable Feedback**: Provide clear remediation steps for any violations +- **Comprehensive Reporting**: Generate detailed compliance reports with scores + +## Workflow Triggers + +```yaml +on: + push: + branches: + - main + - dev/** + - rc/** + pull_request: + branches: + - main + - dev/** + - rc/** + workflow_dispatch: +``` + +**Runs on**: +- Every push to main, dev/*, or rc/* branches +- Every pull request targeting main, dev/*, or rc/* +- Manual trigger via Gitea Actions UI + +## Validation Areas + +The workflow performs 10 comprehensive validation checks organized into two categories: + +### Critical Checks (Must Pass) + +These checks are **blocking** - the workflow will fail if any critical check fails: + +| Check | Description | Validator | Priority | +|-------|-------------|-----------|----------| +| 📁 **Repository Structure** | Validates required directories and files exist | Built-in shell | 🔴 Critical | +| 📚 **Documentation Quality** | Analyzes README, checks documentation completeness | Built-in shell | 🔴 Critical | +| 💻 **Coding Standards** | Runs language-specific linters (Python, PHP, YAML) | yamllint, black, pylint, phpcs | 🔴 Critical | +| ⚖️ **License Compliance** | Validates license file and SPDX identifiers | Built-in shell | 🔴 Critical | +| 🧹 **Git Repository Hygiene** | Checks commit messages, branch naming, .gitignore | Built-in shell | 🔴 Critical | +| ⚙️ **Workflow Configuration** | Validates Gitea Actions workflow files | actionlint, custom checks | 🔴 Critical | +| 🔢 **Version Consistency** | Ensures all version numbers match across repository | check_version_consistency.php | 🔴 Critical | +| 🔐 **Script Integrity** | Validates SHA-256 hashes of critical scripts | validate_script_registry.py | 🔴 Critical | + +### Informational Checks (Non-Blocking) + +These checks provide **recommendations** but don't fail the workflow: + +| Check | Description | Validator | Priority | +|-------|-------------|-----------|----------| +| 🏢 **Enterprise Readiness** | Assesses enterprise-grade features and patterns | check_enterprise_readiness.php | ℹ️ Info | +| 🏥 **Repository Health** | Evaluates overall repository quality metrics | check_repo_health.php | ℹ️ Info | + +## Detailed Check Descriptions + +### 1. Repository Structure Validation + +**What it checks**: +- Required directories: `docs/`, `scripts/`, `.github/` +- Required files: `README.md`, `LICENSE`, `CONTRIBUTING.md`, `SECURITY.md`, `CHANGELOG.md`, `.editorconfig` +- File size and completeness validation + +**Compliance Requirements**: +- All required directories must exist +- All required files must be present +- README must be at least 500 bytes +- LICENSE must be at least 100 bytes + +**Remediation**: +```bash +# Create missing directories +mkdir -p docs scripts .gitea/workflows + +# Create required files from templates +cp templates/docs/required/README.md ./ +cp templates/docs/required/CONTRIBUTING.md ./ +cp templates/docs/required/SECURITY.md ./ +``` + +### 2. Documentation Quality Check + +**What it checks**: +- README.md metrics (size, lines, words, headings, links, code blocks) +- Documentation completeness +- Content quality indicators + +**Compliance Requirements**: +- README minimum 500 bytes, 20 lines, 100 words +- At least 3 headings for structure +- Include links and code examples + +**Scoring**: +- Size: 500+ bytes (good), <500 (warning), >50KB (warning - too long) +- Headings: 3+ (good), <3 (warning) +- Links: 1+ (good), 0 (info - consider adding) +- Code blocks: 1+ (good), 0 (info - consider adding) + +### 3. Coding Standards Validation + +**What it checks**: +- YAML files: Validates syntax and formatting with `yamllint` +- Python files: Code formatting with `black`, linting with `pylint` +- PHP files: Coding standards with `phpcs` (PSR-12) + +**Compliance Requirements**: +- All YAML files must be valid and properly formatted +- Python code must follow Black formatting +- PHP code must follow PSR-12 standards + +**Remediation**: +```bash +# Fix YAML formatting +yamllint --format auto .gitea/workflows/*.yml + +# Fix Python formatting +black scripts/**/*.py + +# Fix PHP code style +phpcs --standard=PSR12 src/ +``` + +### 4. License Compliance + +**What it checks**: +- LICENSE file exists +- File headers contain copyright and SPDX identifiers +- Consistent licensing across repository + +**Compliance Requirements**: +- LICENSE file present at repository root +- All source files include copyright header +- SPDX-License-Identifier present in headers + +**Example Header**: +```php + +// SPDX-License-Identifier: GPL-3.0-or-later +``` + +### 5. Git Repository Hygiene + +**What it checks**: +- Commit message format +- Branch naming conventions +- .gitignore completeness +- No sensitive files in repository + +**Compliance Requirements**: +- Conventional commit messages +- Branch names follow pattern: `feature/*`, `bugfix/*`, `hotfix/*`, `release/*` +- Comprehensive .gitignore file + +### 6. Workflow Configuration Validation + +**What it checks**: +- Valid YAML syntax in workflow files +- Required workflows present +- CodeQL configuration if applicable +- Action version pinning for security + +**Compliance Requirements**: +- All workflows have valid YAML syntax +- Actions pinned to commit hashes for security +- Proper permissions configured + +### 7. Version Consistency Check ⭐ NEW + +**What it checks**: +- All version references match the canonical version in `composer.json` +- Checks 39+ files including: + - Documentation (README.md, CHANGELOG.md, CONTRIBUTING.md) + - Workflows (.gitea/workflows/*.yml) + - PHP source files (src/**/*.php) + - Configuration files + +**Compliance Requirements**: +- Single source of truth: version in `composer.json` +- All references must match exactly +- No version drift across repository + +**Validator**: `api/validate/check_version_consistency.php` + +**Remediation**: +```bash +# Check current status +php api/validate/check_version_consistency.php --verbose + +# Update all version references (if mismatches found) +# Manually update files or use bulk search/replace +``` + +### 8. Script Integrity Validation ⭐ NEW + +**What it checks**: +- SHA-256 hashes of critical scripts match registry +- No unauthorized modifications to security-critical scripts +- Registry file (scripts/.script-registry.json) is up-to-date + +**Compliance Requirements**: +- All scripts in registry must have valid SHA-256 hashes +- Critical priority scripts cannot have mismatches +- Changes to scripts must update registry + +**Validator**: `api/maintenance/validate_script_registry.py` + +**Remediation**: +```bash +# Validate current hashes +python3 api/maintenance/validate_script_registry.py --priority critical + +# Update registry after legitimate changes +python3 api/maintenance/generate_script_registry.py --update + +# Or use auto-update workflow +# .gitea/workflows/auto-update-sha.yml +``` + +### 9. Enterprise Readiness Check ⭐ NEW (Informational) + +**What it checks**: +- Enterprise-grade features implementation +- Security best practices +- Scalability patterns +- Error handling and logging +- Transaction management +- API design patterns + +**Assessment Areas**: +- Architecture patterns +- Error recovery mechanisms +- Monitoring and observability +- Documentation completeness +- Test coverage +- Security controls + +**Validator**: `api/validate/check_enterprise_readiness.php` + +**Note**: This check is **informational only** and does not block merges. It provides recommendations for improving enterprise readiness. + +### 10. Repository Health Check ⭐ NEW (Informational) + +**What it checks**: +- Code quality metrics +- Technical debt indicators +- Dependency health +- Documentation coverage +- Test coverage +- Issue/PR activity + +**Health Metrics**: +- File structure organization +- Code duplication +- Dependency freshness +- Security vulnerabilities +- Community engagement + +**Validator**: `api/validate/check_repo_health.php` + +**Note**: This check is **informational only** and does not block merges. It provides insights for continuous improvement. + +## Compliance Scoring + +The workflow calculates a compliance percentage based on critical checks: + +``` +Compliance % = (Critical Checks Passed / Total Critical Checks) × 100 +``` + +### Score Interpretation + +| Score | Status | Description | +|-------|--------|-------------| +| 100% | ✅ **COMPLIANT** | All critical checks passed - repository fully compliant | +| 80-99% | ⚠️ **MOSTLY COMPLIANT** | Most checks passed - minor issues to address | +| 50-79% | ⚠️ **PARTIALLY COMPLIANT** | Significant issues - requires attention | +| 0-49% | ❌ **NON-COMPLIANT** | Major compliance violations - immediate action required | + +### Example Output + +``` +## ✅ Overall Status: COMPLIANT (100%) + +**Critical Checks:** 8/8 passed +**Total Checks:** 10/10 passed +**Informational:** 0 warning(s) + +████████████████████ 100% + +## Validation Results + +| Area | Status | Result | Priority | +|-----------------------------|---------|------------|-------------| +| 📁 Repository Structure | ✅ Pass | Compliant | - | +| 📚 Documentation Quality | ✅ Pass | Compliant | - | +| 💻 Coding Standards | ✅ Pass | Compliant | - | +| ⚖️ License Compliance | ✅ Pass | Compliant | - | +| 🧹 Git Repository Hygiene | ✅ Pass | Compliant | - | +| ⚙️ Workflow Configuration | ✅ Pass | Compliant | - | +| 🔢 Version Consistency | ✅ Pass | All versions match | - | +| 🔐 Script Integrity | ✅ Pass | SHA hashes validated | - | +| 🏢 Enterprise Readiness | ✅ Pass | Ready for enterprise | ℹ️ Info | +| 🏥 Repository Health | ✅ Pass | Health check passed | ℹ️ Info | +``` + +## Usage Examples + +### Running Manually + +```bash +# Trigger workflow manually via Gitea Actions UI +# Go to: Actions → Standards Compliance → Run workflow + +# Or use GitHub CLI +gh workflow run standards-compliance.yml +``` + +### Local Validation + +Run individual validators locally before pushing: + +```bash +# Check version consistency +php api/validate/check_version_consistency.php --verbose + +# Validate script integrity +python3 api/maintenance/validate_script_registry.py --priority critical --verbose + +# Check enterprise readiness +php api/validate/check_enterprise_readiness.php --verbose + +# Check repository health +php api/validate/check_repo_health.php --verbose + +# Lint YAML files +yamllint .gitea/workflows/*.yml + +# Format Python code +black --check scripts/**/*.py + +# Check PHP code style +phpcs --standard=PSR12 src/ +``` + +### Fixing Common Issues + +#### Version Mismatches + +```bash +# 1. Identify current version +grep '"version"' composer.json + +# 2. Find mismatches +php api/validate/check_version_consistency.php + +# 3. Update all references to match +# Use sed or manually update files listed in output +``` + +#### Script Integrity Violations + +```bash +# If changes are legitimate: +python3 api/maintenance/generate_script_registry.py --update + +# If changes are NOT authorized: +git checkout HEAD -- scripts/ +``` + +#### Coding Standard Violations + +```bash +# Auto-fix Python formatting +black scripts/**/*.py + +# Auto-fix PHP code style +phpcbf --standard=PSR12 src/ + +# Fix YAML issues +# Manual fixes required based on yamllint output +``` + +## Integration with Pull Requests + +The workflow automatically: + +1. **Runs on every PR** to main, dev/*, or rc/* branches +2. **Posts results** in the PR checks section +3. **Provides detailed summary** in the workflow run +4. **Blocks merge** if critical checks fail +5. **Offers remediation steps** for any violations + +### PR Status Checks + +| Check Result | PR Status | Merge Allowed | +|--------------|-----------|---------------| +| All critical checks pass | ✅ Success | Yes | +| Any critical check fails | ❌ Failure | No (blocked) | +| Only informational warnings | ✅ Success | Yes | + +## Workflow Architecture + +``` +┌─────────────────────────────────────────────────────────────┐ +│ PARALLEL VALIDATION CHECKS │ +└─────────────────────────────────────────────────────────────┘ + │ + ├─────────────┬──────────────┬──────────────┬────────────┐ + ▼ ▼ ▼ ▼ ▼ +┌─────────┐ ┌──────────┐ ┌──────────┐ ┌─────────┐ ┌──────────┐ +│Repository │File Header │Code Style│ │ Docs │ │ License │ +│Structure│ │ Validation│ │ Check │ │ Check │ │ Check │ +└─────────┘ └──────────┘ └──────────┘ └─────────┘ └──────────┘ + │ │ │ │ │ + ├─────────────┼──────────────┼──────────────┼────────────┤ + ▼ ▼ ▼ ▼ ▼ +┌─────────┐ ┌──────────┐ ┌──────────┐ ┌─────────┐ ┌──────────┐ +│ Git │ │ Workflow │ │ Version │ │ Script │ │Enterprise│ +│ Hygiene │ │ Config │ │Consistency│ │Integrity│ │Readiness │ +└─────────┘ └──────────┘ └──────────┘ └─────────┘ └──────────┘ + │ │ │ │ │ + └─────────────┴──────────────┴──────────────┴────────────┘ + │ + ▼ + ┌──────────────────┐ + │ All Checks Pass?│ + └──────────────────┘ + │ │ + YES │ │ NO + ▼ ▼ + ┌──────────┐ ┌──────────────┐ + │ SUCCESS │ │ CREATE ISSUE │ + │ Summary │ │ with Failure │ + └──────────┘ │ Details │ + └──────────────┘ +``` + +## Customization + +### Adjusting Severity + +To change a critical check to informational (non-blocking): + +```yaml +# In the summary job, change from: +[ "$CHECK_STATUS" = "success" ] && PASSED=$((PASSED + 1)) || FAILED=$((FAILED + 1)) + +# To: +if [ "$CHECK_STATUS" = "success" ]; then + PASSED=$((PASSED + 1)) +else + WARNINGS=$((WARNINGS + 1)) +fi +``` + +### Adding Custom Checks + +Add a new validation job: + +```yaml +custom-check: + name: Custom Validation + runs-on: ubuntu-latest + steps: + - name: Checkout + uses: actions/checkout@v6 + + - name: Run Custom Validator + run: | + ./scripts/custom-validator.sh +``` + +Then add it to the summary `needs` array. + +### Skipping Checks + +To skip a check temporarily, add to job: + +```yaml +if: false # Skip this check +``` + +Or make conditional: + +```yaml +if: ${{ github.event_name != 'pull_request' }} # Skip on PRs +``` + +## Troubleshooting + +### Workflow Fails Unexpectedly + +**Check**: +1. Review workflow run logs in Gitea Actions +2. Look for specific error messages in failed jobs +3. Check if required scripts exist (new checks depend on PHP/Python scripts) + +**Common Issues**: +- Missing validator scripts (version/enterprise/health checks) +- PHP/Python not available in runner +- Permissions issues with files + +### Version Consistency Always Fails + +**Cause**: Multiple version references across repository don't match + +**Fix**: +1. Identify canonical version: `grep '"version"' composer.json` +2. Find mismatches: `php api/validate/check_version_consistency.php` +3. Update all references to match canonical version + +### Script Integrity Violations + +**Legitimate Changes**: +```bash +# Update registry after modifying scripts +python3 api/maintenance/generate_script_registry.py --update +git add scripts/.script-registry.json +git commit -m "chore: update script registry" +``` + +**Unauthorized Changes**: +```bash +# Restore original scripts +git checkout HEAD -- scripts/ +``` + +## Related Documentation + +- [Workflow Architecture](workflow-architecture) +- [Workflow Inventory](workflow-inventory) +- [Repository Structure Standards](policy-core-structure) +- [Coding Style Guide](policy-coding-style-guide) +- [File Header Standards](policy-file-header-standards) +- [License Compliance Policy](policy-license-compliance) +- [Version Management](guide-version-badge-guide) +- [Script Integrity Guide](guide-script-integrity-validation) + +## Changelog + +### v04.00.04 (2026-02-21) + +**Added**: +- ✨ Version Consistency Check - Validates all version numbers match +- ✨ Script Integrity Validation - Verifies SHA-256 hashes +- ✨ Enterprise Readiness Check - Assesses enterprise patterns (informational) +- ✨ Repository Health Check - Evaluates overall quality (informational) + +**Changed**: +- 📊 Enhanced compliance scoring with critical vs informational distinction +- 📊 Improved summary reporting with detailed breakdowns +- 📊 Total validation checks increased from 6 to 10 + +**Fixed**: +- 🐛 Compliance percentage now correctly calculates based on critical checks only + +### v04.00.04 (2026-01-07) + +**Added**: +- Initial comprehensive standards compliance workflow +- Repository structure validation +- Documentation quality checks +- Coding standards enforcement +- License compliance validation +- Git hygiene checks +- Workflow configuration validation + +--- + +**Maintained by**: moko-platform Team +**Last Review**: 2026-02-21 +**Next Review**: 2026-03-21 --- -**Maintained by**: moko-platform Team -**Last Review**: 2026-02-21 -**Next Review**: 2026-03-21 +*Repo: [moko-platform](https://git.mokoconsulting.tech/MokoConsulting/moko-platform) · [moko-platform wiki](https://git.mokoconsulting.tech/MokoConsulting/moko-platform/wiki/Home)* + +| Field | Value | +|---|---| +| Minimum Version | 04.07.00 | +| Platform | all | +| Applies To | All repositories | + +| Revision | Date | Author | Description | +|---|---|---|---| +| 1.0 | 2026-05-08 | Moko Consulting | Initial version | diff --git a/moko-platform/workflows-static-analysis.-.-.md b/moko-platform/workflows-static-analysis.-.-.md index a1fc211..1e150bc 100644 --- a/moko-platform/workflows-static-analysis.-.-.md +++ b/moko-platform/workflows-static-analysis.-.-.md @@ -1,61 +1,61 @@ ← [Home](Home) -[![moko-platform](https://img.shields.io/badge/moko-platform-05.00.00-orange)](https://git.mokoconsulting.tech/MokoConsulting/moko-platform) - -# PHPStan Static Analysis - -**Status**: ✅ Active | **Version**: 01.00.00 | **Last Updated**: 2026-05-07 - -## Overview - -PHPStan static analysis is integrated into the **Joomla Extension CI** workflow as the `static-analysis` job. It runs after lint-and-validate passes and catches type errors, undefined methods, incorrect return types, and other bugs that PHP lint misses. - -## Configuration - -### Default Behavior (No Config File) - -If no `phpstan.neon` exists in the repo, PHPStan runs at **level 3** (type inference) against `src/`, `htdocs/`, or `lib/`. - -### Custom Config - -Create `phpstan.neon` in the repo root: - -```neon -parameters: - level: 5 - paths: - - src - excludePaths: - - src/vendor - ignoreErrors: - - '#Call to an undefined method#' -``` - -### Analysis Levels - -| Level | What It Checks | -|-------|---------------| -| 0 | Basic checks (unknown classes, functions, methods) | -| 1 | Possibly undefined variables | -| 2 | Unknown methods on `$this` | -| **3** | **Default — return types, type inference** | -| 4 | Dead code, always true/false | -| 5 | Argument types | -| 6-9 | Increasingly strict | - -## Behavior - -- **Non-blocking**: Uses `continue-on-error: true` — failures are reported but don't block PRs -- **Incremental adoption**: Start at level 3, increase as codebase improves -- **Auto-install**: PHPStan is installed if not in composer dependencies - -## Related Documentation - -- [Joomla Extension CI](ci-joomla) -- [Security Audit](security-audit) - -## Changelog - -| Version | Date | Changes | -|---------|------|---------| +[![moko-platform](https://img.shields.io/badge/moko-platform-04.06.00-orange)](https://git.mokoconsulting.tech/MokoConsulting/moko-platform) + +# PHPStan Static Analysis + +**Status**: ✅ Active | **Version**: 01.00.00 | **Last Updated**: 2026-05-07 + +## Overview + +PHPStan static analysis is integrated into the **Joomla Extension CI** workflow as the `static-analysis` job. It runs after lint-and-validate passes and catches type errors, undefined methods, incorrect return types, and other bugs that PHP lint misses. + +## Configuration + +### Default Behavior (No Config File) + +If no `phpstan.neon` exists in the repo, PHPStan runs at **level 3** (type inference) against `src/`, `htdocs/`, or `lib/`. + +### Custom Config + +Create `phpstan.neon` in the repo root: + +```neon +parameters: + level: 5 + paths: + - src + excludePaths: + - src/vendor + ignoreErrors: + - '#Call to an undefined method#' +``` + +### Analysis Levels + +| Level | What It Checks | +|-------|---------------| +| 0 | Basic checks (unknown classes, functions, methods) | +| 1 | Possibly undefined variables | +| 2 | Unknown methods on `$this` | +| **3** | **Default — return types, type inference** | +| 4 | Dead code, always true/false | +| 5 | Argument types | +| 6-9 | Increasingly strict | + +## Behavior + +- **Non-blocking**: Uses `continue-on-error: true` — failures are reported but don't block PRs +- **Incremental adoption**: Start at level 3, increase as codebase improves +- **Auto-install**: PHPStan is installed if not in composer dependencies + +## Related Documentation + +- [Joomla Extension CI](ci-joomla) +- [Security Audit](security-audit) + +## Changelog + +| Version | Date | Changes | +|---------|------|---------| | 01.00.00 | 2026-05-07 | Initial release — level 3 default, non-blocking | diff --git a/moko-platform/workflows-workflow-architecture.-.-.md b/moko-platform/workflows-workflow-architecture.-.-.md index 68455c5..abcda3b 100644 --- a/moko-platform/workflows-workflow-architecture.-.-.md +++ b/moko-platform/workflows-workflow-architecture.-.-.md @@ -1,52 +1,52 @@ ← [Home](Home) -[![moko-platform](https://img.shields.io/badge/moko-platform-05.00.00-orange)](https://git.mokoconsulting.tech/MokoConsulting/moko-platform) - -# Workflow Architecture - -## Overview -> **Important (v2):** All workflows MUST be in `.gitea/workflows/` only. Gitea Actions does not run workflows from `.gitea/workflows/`. Having files in `.gitea/workflows/` creates ghost queued runs that block the runner. - -This document explains the workflow architecture used across Moko Consulting repositories, including the hierarchy, design patterns, reusable workflow patterns, and decision-making processes for workflow selection. - -## Purpose - -This architecture guide provides: - -- **Understanding**: Clear mental model of workflow organization -- **Guidance**: Decision trees for workflow selection -- **Patterns**: Reusable patterns and best practices -- **Relationships**: How workflows interact and depend on each other -- **Evolution**: How to extend and improve the workflow architecture - -## Three-Tier Workflow Architecture - -Moko Consulting uses a three-tier architecture for Gitea Actions workflows: - -``` -┌─────────────────────────────────────────────────────────────┐ -│ Tier 1: Organization-Wide Reusable Workflows │ -│ Location: .github-private repository │ -│ Visibility: Private │ -│ Purpose: Shared across all organization repositories │ -│ Examples: Deployment, compliance audits, security scanning │ -└─────────────────────────────────────────────────────────────┘ - ↓ (called by) -┌─────────────────────────────────────────────────────────────┐ -│ Tier 2: Public Reusable Workflows │ -│ Location: moko-platform repository │ -│ Visibility: Public │ -│ Purpose: Templates and patterns for community use │ -│ Examples: CI validation, build automation, health checks │ -└─────────────────────────────────────────────────────────────┘ - ↓ (called by) -┌─────────────────────────────────────────────────────────────┐ -│ Tier 3: Local Workflows │ -│ Location: Individual repository .gitea/workflows/ │ -│ Visibility: Matches repository visibility │ -│ Purpose: Repository-specific automation │ -│ Examples: Project builds, tests, custom deployments │ -└─────────────────────────────────────────────────────────────┘ -``` - +[![moko-platform](https://img.shields.io/badge/moko-platform-04.06.00-orange)](https://git.mokoconsulting.tech/MokoConsulting/moko-platform) + +# Workflow Architecture + +## Overview +> **Important (v2):** All workflows MUST be in `.gitea/workflows/` only. Gitea Actions does not run workflows from `.gitea/workflows/`. Having files in `.gitea/workflows/` creates ghost queued runs that block the runner. + +This document explains the workflow architecture used across Moko Consulting repositories, including the hierarchy, design patterns, reusable workflow patterns, and decision-making processes for workflow selection. + +## Purpose + +This architecture guide provides: + +- **Understanding**: Clear mental model of workflow organization +- **Guidance**: Decision trees for workflow selection +- **Patterns**: Reusable patterns and best practices +- **Relationships**: How workflows interact and depend on each other +- **Evolution**: How to extend and improve the workflow architecture + +## Three-Tier Workflow Architecture + +Moko Consulting uses a three-tier architecture for Gitea Actions workflows: + +``` +┌─────────────────────────────────────────────────────────────┐ +│ Tier 1: Organization-Wide Reusable Workflows │ +│ Location: .github-private repository │ +│ Visibility: Private │ +│ Purpose: Shared across all organization repositories │ +│ Examples: Deployment, compliance audits, security scanning │ +└─────────────────────────────────────────────────────────────┘ + ↓ (called by) +┌─────────────────────────────────────────────────────────────┐ +│ Tier 2: Public Reusable Workflows │ +│ Location: moko-platform repository │ +│ Visibility: Public │ +│ Purpose: Templates and patterns for community use │ +│ Examples: CI validation, build automation, health checks │ +└─────────────────────────────────────────────────────────────┘ + ↓ (called by) +┌─────────────────────────────────────────────────────────────┐ +│ Tier 3: Local Workflows │ +│ Location: Individual repository .gitea/workflows/ │ +│ Visibility: Matches repository visibility │ +│ Purpose: Repository-specific automation │ +│ Examples: Project builds, tests, custom deployments │ +└─────────────────────────────────────────────────────────────┘ +``` + ### Tier 1: Organization-Wide Reusable Workflows