MokoCLI/docs/workflows/build-release.md

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

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/build-release.md
VERSION: 04.06.00
BRIEF: Build & Release pipeline — unified workflow for version branches, tags, and GitHub Releases
-->

# Build & Release Pipeline

Every governed repo has an `auto-release.yml` workflow that runs a 7-step build and release pipeline on every push to main.

## Pipeline Steps

```
Push to main
  │
  ├─ 1. Read VERSION from README.md
  │
  ├─ 2. Create version/XX branch (snapshot)
  │
  ├─ 3. Set platform version
  │     ├─ Dolibarr: $this->version in mod*.class.php
  │     └─ Joomla: <version> in XML manifest
  │
  ├─ 4. Update [VERSION: XX.YY.ZZ] badges in markdown files
  │
  ├─ 5. Write update.txt (Dolibarr only — plain text version for checkForUpdate)
  │
  ├─ 6. Create git tag vXX.YY.ZZ
  │
  └─ 7. Create GitHub Release with changelog notes
```

## Triggers

- Push to `main` or `master`
- Skips commits by `gitea-actions[bot]` and commits with `[skip ci]`
- Skips if tag + branch already exist (idempotent)

## What Each Step Does

### Step 1: Read version
Reads `VERSION:` from the README.md FILE INFORMATION block using `version_read.php`.

### Step 2: Create version branch
Creates `version/XX` as a frozen snapshot of main at release time. If the branch already exists, this step is skipped.

### Step 3: Set platform version
- **Dolibarr**: sets `$this->version` in `src/core/modules/mod*.class.php` to the real version AND rewrites `$this->url_last_version` to point to the main branch
- **Joomla**: sets `<version>` in XML manifest files

### Step 4: Update version badges
Finds all `[VERSION: XX.YY.ZZ]` badges in markdown files and updates them to the current version.

### Step 5: Write update.txt
For Dolibarr repos only: writes the version number as plain text to `update.txt`. Dolibarr's `checkForUpdate()` expects raw text < 30 chars from `$this->url_last_version`.

### Step 6: Create git tag
Creates `vXX.YY.ZZ` tag and pushes to remote.

### Step 7: Create GitHub Release
Extracts release notes from CHANGELOG.md (section matching the version heading) and creates a GitHub Release targeting the version branch.

## Version Lifecycle

| Phase | Branch | Module Version | Badge | Release? |
|-------|--------|---------------|-------|----------|
| Development | `dev/**` | `"development"` | Dev version | No |
| Merge to main | `main` | Real version | Updated | Yes |
| Version bump | `main` | Auto-incremented | Updated | Next push |

## Stream Tags (v2)Releases use stream-based git tags (`stable`, `release-candidate`, `beta`, `alpha`, `development`), NOT version numbers. To 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### Auto-DetectionThe release workflow 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
## Related Workflows

| Workflow | Role |
|----------|------|
| `sync-version-on-merge.yml` | Auto-bumps patch version in README on push to main |
| `auto-release.yml` | This pipeline — builds, branches, tags, releases |
| `deploy-dev.yml` | Deploys to dev server with version="development" |
| `deploy-demo.yml` | Deploys to demo with real version |
| `repository-cleanup.yml` | Deletes old version branches on schedule |