MokoOnyx/wiki/development.md

← Back to Home

Development

This page covers the repository structure, build process, release workflow, and contributing guidelines for MokoOnyx.

---

Repository Structure

MokoOnyx/
├── src/                          # Template source (this becomes the installable package)
│   ├── component.php             # Component-only page layout
│   ├── error.php                 # Error page layout
│   ├── index.php                 # Main template entry point
│   ├── joomla.asset.json         # Joomla Web Asset Manager definitions
│   ├── offline.php               # Offline page layout
│   ├── script.php                # Install/update/uninstall script
│   ├── sync_custom_vars.php      # CSS variable sync for custom palettes
│   ├── templateDetails.xml       # Joomla template manifest
│   ├── helper/                   # PHP helper classes
│   │   └── minify.php            # CSS/JS auto-minification
│   ├── html/                     # Template overrides (modules, components, layouts)
│   ├── language/                  # Language files (en-GB, en-US)
│   ├── media/                    # Static assets (installed to media/templates/site/mokoonyx/)
│   │   ├── css/                  # Stylesheets
│   │   │   ├── template.css      # Main template stylesheet
│   │   │   ├── editor.css        # Backend editor stylesheet
│   │   │   ├── offline.css       # Offline page styles
│   │   │   ├── a11y-high-contrast.css  # High-contrast accessibility mode
│   │   │   ├── user.css          # User custom CSS (survives updates)
│   │   │   ├── fonts/            # Local font files (Roboto, Noto Sans, Fira Sans)
│   │   │   └── theme/            # Theme palette files
│   │   │       ├── light.standard.css
│   │   │       └── dark.standard.css
│   │   ├── js/                   # JavaScript
│   │   │   ├── template.js       # Main template JS
│   │   │   ├── gtm.js            # Google Tag Manager integration
│   │   │   └── user.js           # User custom JS (survives updates)
│   │   ├── images/               # Template images (bg.svg, etc.)
│   │   ├── fonts/                # Font files
│   │   └── vendor/               # Third-party assets (Font Awesome 7 Free)
│   └── templates/                # Starter files for users
│       ├── light.custom.css      # Custom light palette template
│       ├── dark.custom.css       # Custom dark palette template
│       └── brand-showcase.html   # Brand showcase HTML template
├── Makefile                      # Build and validation automation
├── composer.json                 # PHP dependencies (moko-platform)
├── package.json                  # Node.js dependencies (minification)
├── phpcs.xml                     # PHP CodeSniffer configuration
├── phpstan.neon                  # PHPStan static analysis configuration
├── codeception.yml               # Testing configuration
├── updates.xml                   # Joomla update server manifest
├── tests/                        # Test suites
├── scripts/                      # Build scripts
├── docs/                         # Documentation source
└── build/ / dist/                # Build output (gitignored)

---

Prerequisites

• PHP 8.1+
• Composer (for moko-platform CLI and dependencies)
• Node.js (optional, for build-time minification with terser/clean-css)
• Make (GNU Make or compatible)
• zip (or PowerShell for Windows)

---

Setup

# Clone the repository
git clone https://git.mokoconsulting.tech/MokoConsulting/MokoOnyx.git
cd MokoOnyx

# Install dependencies
make install-deps

---

Building Packages

Build an installable ZIP

make build

This will:

1. Clean previous build artifacts (build/ and dist/)
2. Minify CSS and JS assets
3. Copy src/ contents to build/package/
4. Create dist/mokoonyx-{version}.zip

Build a beta release

make build-beta

Creates dist/mokoonyx-{version}-beta.zip (skips minification).

---

Validation

MokoOnyx uses the moko-platform CLI for code quality checks.

# Run all validation checks
make validate

# Individual checks
make lint             # PHP syntax check
make check-joomla     # Joomla manifest validation
make check-version    # Version consistency across files
make check-xml        # XML well-formedness
make check-headers    # License header verification
make check-secrets    # Credential leak scanning

# Full repository health check
make health

---

Releasing

Full release pipeline

make release

This runs the complete pipeline: validate → build → checksum

After the release package is built:

1. Tag the release: git tag {version}
2. Push tags: git push origin --tags
3. Create a Gitea release and attach the ZIP from dist/

Generate checksums

make checksum

Creates SHA-256 checksums for all ZIP files in dist/.

---

Available Make Targets

Target	Description
make help	Show all available targets
make install-deps	Install Composer dependencies
make update-deps	Update Composer dependencies
make lint	PHP syntax check
make check-joomla	Validate Joomla manifest
make check-version	Verify version consistency
make check-headers	Check license headers
make check-secrets	Scan for leaked credentials
make check-xml	Validate XML files
make validate	Run all validation checks
make health	Full repository health check
make clean	Clean build artifacts
make minify	Minify CSS/JS assets
make build	Build installable ZIP
make build-beta	Build beta release ZIP
make checksum	Generate SHA-256 checksums
make release	Full release pipeline
make version	Display version and extension info
make security-check	Composer security audit
make all	Full pipeline (deps, validate, build, checksum)

---

Contributing

1. Fork the repository on Gitea
2. Create a feature branch from dev
3. Make your changes in src/
4. Run make validate to ensure all checks pass
5. Submit a pull request against dev

Code Standards

• All PHP files must include the GPL-3.0-or-later license header
• PHP code must pass syntax checks and PHPStan analysis
• XML files must be well-formed
• Version numbers must be consistent across README.md, templateDetails.xml, and other version-bearing files
• Attribution goes to Moko Consulting, not individual contributors

Branching Model

Branch	Purpose	Stability Suffix
main	Stable releases	(none)
dev	Active development	-dev
alpha	Alpha pre-releases	-alpha
beta	Beta pre-releases	-beta
rc	Release candidates	-rc
feature/*	Feature development	-dev
version/XX.YY.ZZ	Archived release snapshots	(none)

Version Numbering

Versions use the format XX.YY.ZZ (two-digit segments, zero-padded):

• XX -- Major version (breaking changes)
• YY -- Minor version (new features, bumped on release to main)
• ZZ -- Patch version (auto-incremented on every push to dev/feature branches)

Stability suffixes are appended during development:

• 02.09.00-dev -- Development build
• 02.09.00-alpha -- Alpha pre-release
• 02.09.00-beta -- Beta pre-release
• 02.09.00-rc -- Release candidate

On merge to main, suffixes are stripped and the minor version is bumped.

Auto Version Bump

On every push to dev, alpha, beta, rc, or feature/*:

1. The patch version is incremented (e.g., 02.08.05 -> 02.08.06)
2. The stability suffix is applied based on the branch name
3. All version-bearing files are updated (manifests, CHANGELOG, PHP headers, etc.)
4. A commit is created with [skip ci] to avoid infinite loops

Commits with [skip ci] or [skip bump] in the message are ignored.

Auto Release

When a PR is merged from dev to main:

1. The minor version is bumped (e.g., 02.08.xx -> 02.09.00)
2. Stability suffixes are stripped (stable release)
3. A Gitea release is created with the build package (ZIP + tar.gz + SHA-256)
4. updates.xml is updated for the Joomla update server
5. The dev branch is recreated from main
6. A version/XX.YY.ZZ archive branch is created

Release Channels

The updates.xml file provides update streams for Joomla sites:

Channel	Tag	Description
Development	dev	Latest dev build (or stable if higher)
Alpha	alpha	Alpha pre-release
Beta	beta	Beta pre-release
Release Candidate	rc	RC pre-release
Stable	stable	Production-ready release

Joomla sites check the channel matching their configured stability level.

---

Testing

The repository includes a codeception.yml configuration for automated testing:

# Run tests (requires Codeception via Composer)
vendor/bin/codecept run

---

Built with moko-platform -- Moko Consulting

---

Repo: MokoOnyx · moko-platform

Revision	Date	Author	Description
1.0	2026-05-09	Moko Consulting	Initial version