docs: update CI docs to match current orchestrator

- Update tier numbering to match T1-T4 job names - Fix PR flow diagram to show T2 jobs running in parallel - Add [skip ci] note to push flow - Separate push vs PR path trigger tables - Add workflow file to PR path triggers - Remove Crowdin from orchestrator deploy tier (separate workflow) - Update infrastructure table with correct job names Signed-off-by: Ramon Roche <mrpollo@gmail.com>
2026-04-14 10:07:39 +08:00 · 2026-02-09 10:23:30 -08:00 · 2026-02-09 10:23:30 -08:00 · 89b5a61f79
commit 89b5a61f79
parent 06bb7a6e1b
1 changed files with 60 additions and 55 deletions
--- a/docs/en/test_and_ci/continous_integration.md
+++ b/docs/en/test_and_ci/continous_integration.md
@ -18,47 +18,41 @@ Jobs are organized in tiers, where each tier depends on the previous one complet

 | Tier | Job | PR | Push | Description |
 |------|-----|----|------|-------------|
-| 0 | Detect Changed Paths | Yes | — | Checks if source code files changed (triggers metadata regen) |
-| 1 | Metadata Generation | Yes (conditional) | Yes | Builds PX4 SITL and regenerates all auto-generated docs |
-| 2 | Link Validation | Yes | — | Checks for broken links in changed files, posts PR comment |
-| 3 | Build Site | Yes (gated on Tier 2) | Yes (after Tier 1) | Builds the VitePress documentation site |
-| 4 | Deploy + Crowdin Upload | — | Yes | Deploys to AWS S3 and uploads sources to Crowdin |
+| T1 | Detect Changes | Yes | — | Checks if source code files changed (triggers metadata regen) |
+| T2 | PR Metadata | Yes (conditional) | — | Builds PX4 SITL and regenerates all auto-generated docs |
+| T2 | Metadata Sync | — | Yes | Builds PX4 SITL, regenerates metadata, auto-commits |
+| T2 | Link Check | Yes | — | Checks for broken links in changed files, posts PR comment |
+| T3 | Build Site | Yes (gated on T2) | Yes (after T2) | Builds the VitePress documentation site |
+| T4 | Deploy | — | Yes | Deploys to AWS S3 |

 #### Pull Request Flow

-When a PR modifies files in `docs/**`, the workflow validates the changes:
+When a PR modifies files in `docs/**` or the orchestrator workflow file itself, the workflow validates the changes:

 ```
 PR Event
    │
    ▼
 ┌─────────────────────────────────────┐
-│ Tier 0: Detect Changed Paths       │
+│ T1: Detect Changes                  │
 │  • Checks if src/msg/ROMFS changed  │
 └─────────────────┬───────────────────┘
                  │
-                  ▼
+          ┌───────┴───────┐
+          ▼               ▼
+┌──────────────────┐ ┌─────────────────────────┐
+│ T2: PR Metadata  │ │ T2: Link Check (~30s)   │
+│ (conditional)    │ │  • Detects changed .md   │
+│  • Builds SITL   │ │  • Runs filtered check   │
+│  • Generates     │ │  • Posts PR comment      │
+│    metadata      │ │  • Runs full check       │
+│  • Builds        │ └────────────┬────────────┘
+│    failsafe web  │              │
+└────────┬─────────┘              │
+         └───────────┬────────────┘
+                     ▼
 ┌─────────────────────────────────────┐
-│ Tier 1: PR Metadata Regen          │
-│  (only if source files changed)     │
-│  • Builds px4_sitl_default          │
-│  • Generates parameter/airframe/    │
-│    module documentation             │
-│  • Builds failsafe web simulator    │
-└─────────────────┬───────────────────┘
-                  │
-                  ▼
-┌─────────────────────────────────────┐
-│ Tier 2: Link Validation (~30 sec)  │
-│  • Detects changed docs/en/*.md     │
-│  • Runs filtered link check         │
-│  • Posts sticky PR comment (flaws)  │
-│  • Runs full link check (artifact)  │
-└─────────────────┬───────────────────┘
-                  │
-                  ▼
-┌─────────────────────────────────────┐
-│ Tier 3: Build Site (~7-10 min)     │
+│ T3: Build Site (~7-10 min)         │
 │  (only if link check passed)        │
 │  • Builds VitePress site            │
 │  • Verifies no build errors         │
@ -70,53 +64,53 @@ PR Event

 | Job | Duration | Description |
 |-----|----------|-------------|
-| **Detect Changed Paths** | ~10s | Determines if metadata regeneration is needed |
-| **PR Metadata Regen** | ~10-15m | Rebuilds PX4 SITL and regenerates all metadata (conditional) |
-| **Link Validation** | ~30s | Checks for broken links in changed markdown files and posts a sticky comment to the PR |
-| **Build Site** | ~7-10m | Builds the VitePress site to verify there are no build errors. Gated on link check passing. |
+| **T1: Detect Changes** | ~10s | Determines if metadata regeneration is needed |
+| **T2: PR Metadata** | ~10-15m | Rebuilds PX4 SITL and regenerates all metadata (only if source files changed) |
+| **T2: Link Check** | ~30s | Checks for broken links in changed markdown files and posts a sticky comment to the PR |
+| **T3: Build Site** | ~7-10m | Builds the VitePress site to verify there are no build errors. Gated on link check passing. |

 #### Push Flow (main/release branches)

-When changes are pushed to `main` or `release/**` branches, the workflow regenerates metadata, builds, and deploys:
+When changes are pushed to `main` or `release/**` branches that affect docs or source paths, the workflow regenerates metadata, builds, and deploys:

 ```
 Push Event
    │
    ▼
 ┌─────────────────────────────────────┐
-│ Tier 1: Regenerate Metadata         │
-│  (~10-15 min)                       │
+│ T2: Metadata Sync (~10-15 min)     │
 │  • Builds px4_sitl_default          │
 │  • Generates parameter/airframe/    │
 │    module documentation             │
 │  • Builds failsafe web simulator    │
 │  • Formats with Prettier            │
 │  • Auto-commits if changes detected │
+│    (with [skip ci])                 │
 └─────────────────┬───────────────────┘
                  │
                  ▼
 ┌─────────────────────────────────────┐
-│ Tier 3: Build Site (~7-10 min)     │
+│ T3: Build Site (~7-10 min)         │
 │  • Builds VitePress site            │
 │  • Uploads build artifact           │
 └─────────────────┬───────────────────┘
                  │
-          ┌───────┴───────┐
-          ▼               ▼
-┌──────────────┐  ┌──────────────────┐
-│ Tier 4:      │  │ Tier 4:          │
-│ Deploy to    │  │ Crowdin Upload   │
-│ AWS (~3 min) │  │ (~4 min)         │
-│ • S3 sync    │  │ • Upload sources │
-└──────────────┘  └──────────────────┘
+                  ▼
+┌─────────────────────────────────────┐
+│ T4: Deploy (~3 min)                │
+│  • Syncs to AWS S3                  │
+│  • HTML: 60s cache                  │
+│  • Assets: 24h immutable cache      │
+└─────────────────────────────────────┘
 ```

 | Job | Duration | Description |
 |-----|----------|-------------|
-| **Regenerate Metadata** | ~10-15m | Rebuilds PX4 SITL, regenerates all metadata, formats with Prettier, auto-commits |
-| **Build Site** | ~7-10m | Builds the VitePress documentation site |
-| **Deploy to AWS** | ~3m | Syncs built site to AWS S3 (HTML: 60s cache, assets: 24h cache) |
-| **Crowdin Upload** | ~4m | Uploads English source files to Crowdin for translation (main branch only) |
+| **T2: Metadata Sync** | ~10-15m | Rebuilds PX4 SITL, regenerates all metadata, formats with Prettier, auto-commits with `[skip ci]` |
+| **T3: Build Site** | ~7-10m | Builds the VitePress documentation site |
+| **T4: Deploy** | ~3m | Syncs built site to AWS S3 (HTML: 60s cache, assets: 24h cache) |
+
+Crowdin upload is handled by a separate workflow (see below).

 #### Generated Metadata

@ -137,7 +131,9 @@ Do not manually edit the auto-generated files listed above. They are overwritten

 #### Path Triggers

-The workflow triggers on changes to these paths:
+The workflow triggers on different paths depending on the event:
+
+**Push** (main/release branches):

 | Path | Reason |
 |------|--------|
@ -147,6 +143,15 @@ The workflow triggers on changes to these paths:
 | `ROMFS/**` | ROMFS files affect metadata |
 | `Tools/module_config/**` | Module configuration affects metadata |

+**Pull Request:**
+
+| Path | Reason |
+|------|--------|
+| `docs/**` | Documentation source files |
+| `.github/workflows/docs-orchestrator.yml` | Changes to the workflow itself |
+
+Source-only changes on PRs are detected at runtime by the T1: Detect Changes job using [dorny/paths-filter](https://github.com/dorny/paths-filter), which conditionally triggers the T2: PR Metadata job.
+
 ### Crowdin Download Workflow

 **Workflow file:** [`docs_crowdin_download.yml`](https://github.com/PX4/PX4-Autopilot/blob/main/.github/workflows/docs_crowdin_download.yml)
@ -179,9 +184,9 @@ Jobs run on [runs-on](https://runs-on.com/) self-hosted runners with S3 cache:

 | Job | Runner |
 |-----|--------|
-| Detect Changed Paths | ubuntu-latest |
-| Link Validation | ubuntu-latest |
-| Metadata Regen | 4 CPU (with px4-dev container) |
-| Build Site | 4 CPU |
-| Deploy to AWS | ubuntu-latest |
-| Crowdin Upload | ubuntu-latest |
+| T1: Detect Changes | ubuntu-latest |
+| T2: PR Metadata | 4 CPU (with px4-dev container) |
+| T2: Metadata Sync | 4 CPU (with px4-dev container) |
+| T2: Link Check | ubuntu-latest |
+| T3: Build Site | 4 CPU |
+| T4: Deploy | ubuntu-latest |