[](https://git.mokoconsulting.tech/MokoConsulting/MokoStandards) # Release System ## Overview The MokoStandards 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 `.github/workflows/`. Having files in `.github/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