moko-platform/docs/workflows/auto-release.md

Auto Release

Creates or updates a GitHub Release on every push to main. Uses major-only tags (vXX) — one release per major version, with all minor+patch versions appending notes and assets to the same release.

Platform-Specific Pipelines

Generic Repos

1. Reads VERSION: from README.md FILE INFORMATION block (e.g., 04.06.00)
2. Extracts major version (e.g., 04)
3. Creates or updates the v04 tag on the release commit
4. Creates or updates the v04 GitHub Release, appending changelog notes for this version
5. Auto-bumps patch version with [skip ci] commit
6. Auto-creates version/XX archive branch

Joomla Repos (waas-component)

Joomla repos do not use FTP deploy. Distribution is via GitHub Release ZIPs.

1. Reads VERSION: from README.md FILE INFORMATION block
2. Builds installable ZIP from src/ directory
3. Computes SHA-256 hash of the ZIP
4. Uploads ZIP as an asset to the vXX GitHub Release (e.g., com_myextension-01.02.03.zip)
5. Updates updates.xml with the stable entry: version, download URL, and SHA-256 hash
6. Creates or updates the vXX tag and release, appending changelog notes
7. Auto-bumps patch version with [skip ci] commit
8. Auto-creates version/XX archive branch

Dolibarr Repos (crm-module, crm-platform)

1. Reads VERSION: from README.md FILE INFORMATION block
2. Updates $this->version in mod*.class.php to the real version
3. Updates update.txt with the stable version string
4. Creates or updates the vXX tag and release, appending changelog notes
5. Auto-bumps patch version with [skip ci] commit
6. Auto-creates version/XX archive branch

Triggers

• Push to main or master
• Skips commits by gitea-actions[bot] and commits with [skip ci]

Version Lifecycle

Phase	Branch	Module Version	Release?
Development	dev/**	XX.YY.00 (patch 00 = dev)	No
Alpha (optional)	alpha/**	XX.YY.ZZ	alpha tag release
Beta (optional)	beta/**	XX.YY.ZZ	beta tag release
Release Candidate	rc/**	XX.YY.ZZ (patch >= 01)	release-candidate tag (draft release created on RC branch creation)
Merge to main	main	Real version (e.g., 01.02.01)	Yes — vXX tag + release
Auto-bump	main	Auto-incremented patch	No (skipped by [skip ci])

Note: Alpha and beta stages are optional. Dev can go directly to rc when not needed.

Release Tags

Each stability level has its own GitHub Release tag:

Tag	Stability	Source
development	Development	dev/** branches
alpha	Alpha	alpha/** branches
beta	Beta	beta/** branches
release-candidate	RC	rc/** branches
vXX	Stable production	main (major only, e.g., v04)

• The vXX production tag is major only — one GitHub Release per major version
• All minor+patch versions append release notes and ZIP assets to the same vXX release
• No minor or patch production tags are created
• Pre-release tags are updated in-place per stability level

Stream Tags (v2)Releases 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 Releases)Stable releases keep up to 5 previous versions in the Gitea release body.

Requirements

• secrets.GH_TOKEN with contents: write permission
• VERSION: field in README.md FILE INFORMATION block
• .mokostandards file with platform: field (joomla, dolibarr, or generic)

Changelog Extraction

The workflow extracts release notes from CHANGELOG.md by finding the section header that matches the version number. If no match is found, it uses "Release {VERSION}" as the fallback.

Draft Release (RC Branches)

When an rc/** branch is created, the branch tracking system auto-creates a draft GitHub Release for the vXX major version. This draft is later published by auto-release.yml when the RC merges to main. See Dev Branch Tracking for details.