Jonathan Miller
3a30f1a088
Generic: Repo Health / Site Health (push) Has been skipped
Generic: Repo Health / Site Health (pull_request) Has been skipped
Generic: Repo Health / Access control (push) Successful in 6s
Universal: PR Check / Branch Policy (pull_request) Successful in 3s
Generic: Repo Health / Access control (pull_request) Successful in 3s
Universal: Auto Version Bump / Version Bump (push) Failing after 14s
Joomla: Extension CI / Release Readiness Check (pull_request) Failing after 12s
Universal: Secret Scanning / Gitleaks Secret Scan (pull_request) Successful in 11s
Universal: PR Check / Validate PR (pull_request) Failing after 10s
Update Server / Update Server (push) Successful in 18s
Joomla: Extension CI / Lint & Validate (pull_request) Failing after 35s
Joomla: Extension CI / Tests (PHP 8.2) (pull_request) Has been cancelled
Joomla: Extension CI / Tests (PHP 8.3) (pull_request) Has been cancelled
Joomla: Extension CI / PHPStan Analysis (pull_request) Has been cancelled
Joomla: Extension CI / Build RC Pre-Release (pull_request) Has been cancelled
Generic: Repo Health / Release configuration (push) Has been cancelled
Generic: Repo Health / Scripts governance (push) Has been cancelled
Generic: Repo Health / Repository health (push) Has been cancelled
Universal: PR Check / Build RC Package (pull_request) Has been cancelled
Generic: Repo Health / Release configuration (pull_request) Has been cancelled
Generic: Repo Health / Scripts governance (pull_request) Has been cancelled
Generic: Repo Health / Repository health (pull_request) Has been cancelled
# Conflicts: # .mokogitea/cascade-dev.yml # src/templateDetails.xml # updates.xml
290 lines
9.6 KiB
Markdown
290 lines
9.6 KiB
Markdown
[← Back to Home](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
|
|
|
|
```bash
|
|
# 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
|
|
|
|
```bash
|
|
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
|
|
|
|
```bash
|
|
make build-beta
|
|
```
|
|
|
|
Creates `dist/mokoonyx-{version}-beta.zip` (skips minification).
|
|
|
|
---
|
|
|
|
## Validation
|
|
|
|
MokoOnyx uses the **moko-platform CLI** for code quality checks.
|
|
|
|
```bash
|
|
# 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
|
|
|
|
```bash
|
|
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
|
|
|
|
```bash
|
|
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](https://git.mokoconsulting.tech/MokoConsulting/MokoOnyx)
|
|
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:
|
|
|
|
```bash
|
|
# Run tests (requires Codeception via Composer)
|
|
vendor/bin/codecept run
|
|
```
|
|
|
|
---
|
|
|
|
*Built with [moko-platform](https://git.mokoconsulting.tech/MokoConsulting/moko-platform) -- Moko Consulting*
|
|
|
|
---
|
|
|
|
*Repo: [MokoOnyx](https://git.mokoconsulting.tech/MokoConsulting/MokoOnyx) · [moko-platform](https://git.mokoconsulting.tech/MokoConsulting/moko-platform/wiki/Home)*
|
|
|
|
| Revision | Date | Author | Description |
|
|
|---|---|---|---|
|
|
| 1.0 | 2026-05-09 | Moko Consulting | Initial version |
|
|
|