Jonathan Miller
89 lines
4.1 KiB
Markdown
89 lines
4.1 KiB
Markdown
<!--
|
|
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 |
|