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

<!--
Copyright (C) 2026 Moko Consulting <hello@mokoconsulting.tech>

This file is part of a Moko Consulting project.

SPDX-License-Identifier: GPL-3.0-or-later

# FILE INFORMATION
DEFGROUP: MokoStandards.Documentation
INGROUP: MokoStandards
REPO: https://git.mokoconsulting.tech/MokoConsulting/MokoStandards-API
PATH: /docs/workflows/auto-release.md
VERSION: 04.06.00
BRIEF: Guide for the auto-release workflow — creates GitHub Releases on merge to main
-->

[![MokoStandards](https://img.shields.io/badge/MokoStandards-04.06.00-orange)](https://git.mokoconsulting.tech/MokoConsulting/MokoStandards)

# 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](./dev-branch-tracking.md) for details.