MokoOnyx/wiki/development.md

[← 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 |