MokoConsulting/moko-platform

Fork 0

Table of Contents

Release System

Overview
Release Lifecycle

Version Numbering
Branch Flow
Release Tags

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 <sha256></sha256> empty — Joomla fails checksum verification on empty tags- Omit the <sha256> tag entirely if no hash is available- Always set SHA when building a package## creationDateAlways update <creationDate> 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 <element> 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.

Standard Release Process

Platform-Specific Pipelines

Generic Repos
Joomla Repos (waas-component)
Dolibarr Repos (crm-module, crm-platform)

Version Format Summary
Version Detection
Skipping Releases
Architecture

Full Release Cycle
Auto-Release Pipeline (on push to main)

Configuration Files
Best Practices
Last Updated: 2026-04-07 Maintained by: Moko Consulting Infrastructure Team

← Home

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)

dev/XX.YY or dev/feature-name — Active development. Patch is 00. No release.
alpha/XX.YY.ZZ — (Optional) Early internal testing. Can be skipped — dev can go straight to rc.
beta/XX.YY.ZZ — (Optional) Broader external testing. Can be skipped — dev can go straight to rc.
rc/XX.YY.ZZ — Release candidate. Three-part version required (patch >= 01). Auto-creates tracking issue + draft GitHub Release.
version/XX — Major version integration branch (major number only, e.g., version/04). All minors and patches flow into the same major branch.
main — Production. Push triggers auto-release.yml which publishes the GitHub Release, creates/updates the major tag, and auto-bumps patch.
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 `<sha256></sha256>` empty — Joomla fails checksum verification on empty tags- Omit the `<sha256>` tag entirely if no hash is available- Always set SHA when building a package## creationDateAlways update `<creationDate>` 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 `<element>` 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

Start development: Create dev/XX.YY branch from main
Develop: Work on the dev branch with version set to XX.YY.00
Alpha testing (optional): Create alpha/XX.YY.ZZ branch from dev for early internal testing. Can be skipped.
Beta testing (optional): Create beta/XX.YY.ZZ branch from alpha (or dev) for broader external testing. Can be skipped.
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
Test RC: Fix bugs on the RC branch. Deploy to dev server for final testing
Merge to version/XX: Merge RC to the version/XX major integration branch
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
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:

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

Patch 00 is always dev — never release from patch 00
RC before release — always go through rc/ before merging to main (alpha/beta are optional)
Alpha and beta are optional — dev can go straight to rc when internal/external testing stages are not needed
One major release object — all minor+patch append to the same vXX GitHub Release
Let auto-bump handle patch — don't manually bump patch on main
Write clear changelog entries before creating RC
Test RC on dev server — RC branches deploy to dev FTP (Dolibarr/Generic) or generate dev updates.xml entries (Joomla)
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

Repo: moko-platform · moko-platform wiki

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