diff options
Diffstat (limited to 'archived/projt-launcher/docs/handbook/workflows.md')
| -rw-r--r-- | archived/projt-launcher/docs/handbook/workflows.md | 226 |
1 files changed, 226 insertions, 0 deletions
diff --git a/archived/projt-launcher/docs/handbook/workflows.md b/archived/projt-launcher/docs/handbook/workflows.md new file mode 100644 index 0000000000..8b9a658cc9 --- /dev/null +++ b/archived/projt-launcher/docs/handbook/workflows.md @@ -0,0 +1,226 @@ +# GitHub Actions Workflows + +> **Location**: `.github/workflows/` +> **Platform**: GitHub Actions +> **Type**: CI/CD Pipeline +> **Latest Version**: 0.0.5-1 + +--- + +## Overview + +ProjT Launcher uses a modular GitHub Actions workflow architecture. The CI system is split into specialized sub-workflows that are orchestrated by a main coordinator workflow. + +--- + +## Workflow Architecture + +``` +┌─────────────────────────────────────────────────────────────┐ +│ ci-new.yml │ +│ (Main Orchestrator) │ +├─────────────────────────────────────────────────────────────┤ +│ │ +│ ┌─────────────┐ ┌─────────────┐ ┌─────────────────────┐ │ +│ │ ci-prepare │ │ ci-lint │ │ ci-release │ │ +│ │ .yml │ │ .yml │ │ .yml │ │ +│ └─────────────┘ └─────────────┘ └─────────────────────┘ │ +│ │ +│ ┌─────────────────────────────────────────────────────┐ │ +│ │ Library Workflows │ │ +│ │ ┌─────────┐ ┌─────────┐ ┌─────────┐ ┌───────────┐ │ │ +│ │ │ci-zlib │ │ci-bzip2 │ │ci-quazip│ │ ci-cmark │ │ │ +│ │ │ .yml │ │ .yml │ │ .yml │ │ .yml │ │ │ +│ │ └─────────┘ └─────────┘ └─────────┘ └───────────┘ │ │ +│ │ ┌──────────────┐ ┌────────────────┐ │ │ +│ │ │ci-tomlplusplus│ │ ci-libqrencode │ │ │ +│ │ │ .yml │ │ .yml │ │ │ +│ │ └──────────────┘ └────────────────┘ │ │ +│ └─────────────────────────────────────────────────────┘ │ +│ │ +│ ┌─────────────┐ ┌─────────────┐ ┌─────────────────────┐ │ +│ │ ci-website │ │ci-scheduled │ │ (unlock) │ │ +│ │ .yml │ │ .yml │ │ Merge Gate │ │ +│ └─────────────┘ └─────────────┘ └─────────────────────┘ │ +│ │ +└─────────────────────────────────────────────────────────────┘ +``` + +--- + +## Workflow Files + +### Main Orchestrator + +| File | Description | +|------|-------------| +| `ci-new.yml` | Main coordinator that calls all sub-workflows with conditional logic | + +### Core Workflows + +| File | Purpose | Triggers | +|------|---------|----------| +| `ci-prepare.yml` | Initial setup, dependency caching | Called by main | +| `ci-lint.yml` | Code quality checks (clang-format, linters) | Push, PR, Manual | +| `ci-release.yml` | Build releases, create artifacts | Release, Manual | +| `ci-website.yml` | Build and deploy website | Push, PR | +| `ci-scheduled.yml` | Scheduled maintenance tasks | Cron | + +### Library Workflows + +Each bundled library has its own independent CI: + +| File | Library | Tests | +|------|---------|-------| +| `ci-zlib.yml` | zlib | Compression tests | +| `ci-bzip2.yml` | bzip2 | Compression + valgrind | +| `ci-quazip.yml` | QuaZip | Qt ZIP operations | +| `ci-cmark.yml` | cmark | Markdown parsing | +| `ci-tomlplusplus.yml` | toml++ | TOML parsing | +| `ci-libqrencode.yml` | libqrencode | QR generation | + +--- + +## Workflow Design Principles + +### 1. Modular Architecture + +Each workflow is self-contained and can be run independently: + +```yaml +# Sub-workflow pattern +on: + workflow_call: + inputs: + ref: + required: false + type: string + push: + paths: + - 'library-name/**' + pull_request: + paths: + - 'library-name/**' +``` + +### 2. Centralized Control + +The main orchestrator (`ci-new.yml`) controls when each sub-workflow runs: + +```yaml +jobs: + call-zlib: + if: needs.prepare.outputs.run-zlib == 'true' + uses: ./.github/workflows/ci-zlib.yml +``` + +### 3. Path Filtering + +Workflows only run when relevant files change: + +```yaml +paths: + - 'zlib/**' + - '.github/workflows/ci-zlib.yml' +``` + +### 4. Merge Gate + +The `unlock` job aggregates all results for merge protection: + +{% raw %} +```yaml +unlock: + needs: [lint, build, test-zlib, test-bzip2, ...] + if: always() + runs-on: ubuntu-latest + steps: + - name: Check all jobs + run: | + if [[ "${{ contains(needs.*.result, 'failure') }}" == "true" ]]; then + exit 1 + fi +``` +{% endraw %} + +--- + +## Triggers + +| Trigger | Workflows | Description | +|---------|-----------|-------------| +| `push` | All | Commits to main branches | +| `pull_request` | All | Pull request changes | +| `release` | Release | GitHub releases | +| `schedule` | Scheduled | Cron jobs | +| `workflow_dispatch` | All | Manual triggers | +| `workflow_call` | Sub-workflows | Called by orchestrator | + +--- + +## Environment Variables + +| Variable | Description | +|----------|-------------| +| `GITHUB_TOKEN` | Automatic GitHub token | +| `MSA_CLIENT_ID` | Microsoft Auth client ID | +| `CACHIX_AUTH_TOKEN` | Nix cache auth | + +--- + +## Adding New Workflows + +1. **Create the workflow file** in `.github/workflows/` +2. **Add workflow_call trigger** for orchestrator integration +3. **Add push/PR triggers** for independent execution +4. **Update ci-new.yml** to include the new workflow +5. **Document** in this handbook + +### Template + +{% raw %} +```yaml +name: CI Library Name + +on: + workflow_call: + inputs: + ref: + required: false + type: string + push: + paths: + - 'library-name/**' + - '.github/workflows/ci-libraryname.yml' + pull_request: + paths: + - 'library-name/**' + - '.github/workflows/ci-libraryname.yml' + +jobs: + build: + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v4 + with: + ref: ${{ inputs.ref || github.ref }} + # Build steps... +``` +{% endraw %} + +--- + +## Related Documentation + +- [CI Support Files](./ci_support.md) — Configuration files +- [CI Evaluation](./ptcieval.md) — Nix-based validation +- [GitHub Scripts](./ptcigh.md) — Automation helpers +- [Bot](./bot.md) — PR automation + +--- + +## External Links + +- [GitHub Actions Documentation](https://docs.github.com/en/actions) +- [Workflow Syntax](https://docs.github.com/en/actions/reference/workflow-syntax-for-github-actions) +- [Reusable Workflows](https://docs.github.com/en/actions/using-workflows/reusing-workflows) |