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

## 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.
feat: add templates, CLI dirs, docs, and Gitea-first platform config 2026-04-15 02:35:30 +00:00			`<!--`
			`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`
docs: update all references to MokoConsulting org and Gitea URLs 2026-04-16 22:21:59 -05:00			`REPO: https://git.mokoconsulting.tech/MokoConsulting/MokoStandards-API`
feat: add templates, CLI dirs, docs, and Gitea-first platform config 2026-04-15 02:35:30 +00:00			`PATH: /docs/workflows/auto-release.md`
			`VERSION: 04.06.00`
			`BRIEF: Guide for the auto-release workflow — creates GitHub Releases on merge to main`
			`-->`

docs: update all references to MokoConsulting org and Gitea URLs 2026-04-16 22:21:59 -05:00			`[![MokoStandards](https://img.shields.io/badge/MokoStandards-04.06.00-orange)](https://git.mokoconsulting.tech/MokoConsulting/MokoStandards)`
feat: add templates, CLI dirs, docs, and Gitea-first platform config 2026-04-15 02:35:30 +00:00
			`# 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`
Complete Gitea-primary migration: templates, docs, bot identity 2026-04-16 23:00:59 -05:00			- Skips commits by `gitea-actions[bot]` and commits with `[skip ci]`
feat: add templates, CLI dirs, docs, and Gitea-first platform config 2026-04-15 02:35:30 +00:00
			`## 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`

			`## 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.