doc(GH-Actions): add detailed vocabulary section with diagrams#5607
doc(GH-Actions): add detailed vocabulary section with diagrams#5607renecannao merged 3 commits intov3.0from
Conversation
…diagrams The existing CI architecture doc assumes the reader already knows the GitHub Actions terminology and can parse check-run labels like 'CI-maketest / builds (testgalera)'. A maintainer asked what that label means and where to find it by grep, and the only answer was "re-read the whole doc and work it out yourself, most of the pieces are in different sections". That's not good enough. This commit adds a new §12 'Understanding GitHub Actions vocabulary' that: - Walks through the seven core terms (workflow, workflow run, job, matrix cell, step, check run, caller/reusable split) bottom-up, using ci-maketest.yml as a single concrete example throughout. - Includes an ASCII nesting diagram that shows how workflow -> run -> job -> matrix cell -> steps slot into each other, with check runs as separate objects attached to the commit SHA. - Includes a second ASCII diagram showing the ProxySQL two-branch caller/reusable split: one logical trigger -> two workflow runs, one on v3.0 and one on GH-Actions, sharing the same workflow name. - Includes a third diagram tracing exactly how the check-run label 'CI-maketest / builds (testgalera)' is assembled at runtime from github.workflow + github.job + env.MATRIX, explaining why the literal string exists nowhere on disk and grepping for it or for 'galera' will fail. - Answers five common confusion questions directly (why click-throughs land on GH-Actions, why two check rows per cell, where 'make testgalera' is defined, which file produced a given check row, CI-legacy-g2-genai vs CI-legacy-g2). - Ends with a five-question self-test so the reader can check they have the model right before closing the section. Also: - Added a 'New to GitHub Actions terminology?' pointer at the top of the doc so a confused reader jumps directly to the new section instead of wading through the two-branch architecture explanation first. - Renamed the existing compact Glossary table to 'Glossary (quick reference)' to make clear it is the lookup-by-term reference and the new narrative section is the learn-by-walkthrough explanation. - Both sections are kept: §12 for people who need the model, §13 for people who just need a word defined quickly. No source-code or workflow changes. Doc only.
📝 WalkthroughWalkthroughInserted a new long-form section "Understanding GitHub Actions vocabulary — read this first if confused" into Changes
Estimated code review effort🎯 2 (Simple) | ⏱️ ~10 minutes Possibly related PRs
Poem
🚥 Pre-merge checks | ✅ 3✅ Passed checks (3 passed)
✏️ Tip: You can configure your own custom pre-merge checks in the settings. ✨ Finishing Touches🧪 Generate unit tests (beta)
Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out. Comment |
![gemini-code-assist[bot]](https://avatars.githubusercontent.com/in/956858?s=60&v=4){kind=small}
There was a problem hiding this comment.
Code Review
This pull request significantly expands the GitHub Actions documentation by adding a detailed vocabulary section that explains the hierarchy of workflows, jobs, and check runs, specifically addressing the complex two-branch architecture used in ProxySQL. Feedback focuses on correcting minor grammatical errors, addressing a comma splice, and improving the usability of YAML code snippets by replacing decorative arrows with standard comment syntax.
| on disk corresponds to this row, and why can't I find it by grepping?"*, | ||
| read this section. | ||
|
|
||
| We will use **one concrete check label** throughout — the one from issue |
There was a problem hiding this comment.
Missing the definite article "the" before "issue".
| We will use **one concrete check label** throughout — the one from issue | |
| We will use **one concrete check label** throughout — the one from the issue |
|
|
||
| The workflow's **identity in the GitHub UI is the `name:` field**, not the | ||
| filename. Two different files with the same `name:` will look like "the | ||
| same workflow" in the UI (this is important — ProxySQL does exactly this, |
There was a problem hiding this comment.
This is a comma splice. Using a semicolon or a period would improve the grammatical correctness of the parenthetical statement.
| same workflow" in the UI (this is important — ProxySQL does exactly this, | |
| same workflow" in the UI (this is important — ProxySQL does exactly this; |
| name: CI-maketest ← ← ← this is the workflow name | ||
| on: | ||
| workflow_dispatch: | ||
| workflow_call: | ||
| inputs: | ||
| trigger: | ||
| type: string | ||
| target: | ||
| type: string | ||
| jobs: | ||
| builds: ← there is exactly one job: "builds" |
There was a problem hiding this comment.
Use standard YAML comments (#) instead of arrows (←) to ensure the code snippet remains valid and can be copied/pasted without errors.
| name: CI-maketest ← ← ← this is the workflow name | |
| on: | |
| workflow_dispatch: | |
| workflow_call: | |
| inputs: | |
| trigger: | |
| type: string | |
| target: | |
| type: string | |
| jobs: | |
| builds: ← there is exactly one job: "builds" | |
| name: CI-maketest # this is the workflow name | |
| on: | |
| workflow_dispatch: | |
| workflow_call: | |
| inputs: | |
| trigger: | |
| type: string | |
| target: | |
| type: string | |
| jobs: | |
| builds: # there is exactly one job: "builds" |
| ``` | ||
|
|
||
| This file *is* a workflow. It will stay a workflow whether it ever runs or | ||
| not, whether it has runs on 10 commits or zero commits. It is an |
There was a problem hiding this comment.
Grammatical error: "has runs" should be "has run" (past participle).
| not, whether it has runs on 10 commits or zero commits. It is an | |
| not, whether it has run on 10 commits or zero commits. It is an |
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 1
🧹 Nitpick comments (1)
doc/GH-Actions/README.md (1)
1012-1012: Optional: Consider language specifiers for fenced code blocks (or ignore).markdownlint flags these fenced code blocks as missing language specifiers. Since these blocks contain ASCII diagrams rather than code, you have two acceptable options:
Add
textspecifier to silence the linter:```text CI-maketest / builds (testgalera) ```Leave as-is — the diagrams render fine without specifiers, and the warning is purely cosmetic.
Also note: LanguageTool's suggestions to change
.githubto.GitHubare false positives—the actual directory name in GitHub repositories is.github(lowercase). Please disregard those warnings.Also applies to: 1121-1121, 1144-1144, 1177-1177, 1249-1289, 1309-1352, 1368-1401
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@doc/GH-Actions/README.md` at line 1012, The fenced code blocks containing ASCII diagrams in doc/GH-Actions/README.md are flagged by markdownlint for missing language specifiers; either add a `text` language tag to each relevant fenced block (e.g., replace ``` with ```text for the ASCII diagram blocks found around the sections noted) or deliberately leave them unchanged; additionally, ignore LanguageTool suggestions to change the directory name `.github` to `.GitHub` since the correct repo directory is lowercase `.github`.
🤖 Prompt for all review comments with AI agents
Verify each finding against the current code and only fix it if needed.
Inline comments:
In `@doc/GH-Actions/README.md`:
- Around line 13-18: Update the two hard-coded links that point to the
"Understanding GitHub Actions vocabulary — read this first if confused" section
so their anchors use a single hyphen instead of a double-hyphen; specifically
change the link target
"#understanding-github-actions-vocabulary--read-this-first-if-confused" (found
in the forward pointer and the TOC entry) to
"#understanding-github-actions-vocabulary-read-this-first-if-confused" to match
the auto-generated anchor for the heading "Understanding GitHub Actions
vocabulary — read this first if confused".
---
Nitpick comments:
In `@doc/GH-Actions/README.md`:
- Line 1012: The fenced code blocks containing ASCII diagrams in
doc/GH-Actions/README.md are flagged by markdownlint for missing language
specifiers; either add a `text` language tag to each relevant fenced block
(e.g., replace ``` with ```text for the ASCII diagram blocks found around the
sections noted) or deliberately leave them unchanged; additionally, ignore
LanguageTool suggestions to change the directory name `.github` to `.GitHub`
since the correct repo directory is lowercase `.github`.
🪄 Autofix (Beta)
Fix all unresolved CodeRabbit comments on this PR:
- Push a commit to this branch (recommended)
- Create a new PR with the fixes
ℹ️ Review info
⚙️ Run configuration
Configuration used: Organization UI
Review profile: CHILL
Plan: Pro
Run ID: 4bcfcd62-ce18-407e-b268-119d2fccace6
📒 Files selected for processing (1)
doc/GH-Actions/README.md
📜 Review details
🧰 Additional context used
🪛 LanguageTool
doc/GH-Actions/README.md
[uncategorized] ~1027-~1027: The official name of this software platform is spelled with a capital “H”.
Context: ...workflow* is exactly one file under .github/workflows/. Each file has a top-level ...
(GITHUB)
[uncategorized] ~1201-~1201: The official name of this software platform is spelled with a capital “H”.
Context: ...ce | Value at runtime | |---|---|---| | ${{ github.workflow }} | the workflow's name: f...
(GITHUB)
[uncategorized] ~1202-~1202: The official name of this software platform is spelled with a capital “H”.
Context: ...low's name: field | CI-maketest | | ${{ github.job }} | the job key | builds | | `$...
(GITHUB)
[uncategorized] ~1223-~1223: The official name of this software platform is spelled with a capital “H”.
Context: ...t branch (v3.0). - A caller is a .github/workflows/CI-*.yml file on v3.0 (upp...
(GITHUB)
[uncategorized] ~1226-~1226: The official name of this software platform is spelled with a capital “H”.
Context: ...the other branch. - A reusable is a .github/workflows/ci-*.yml file on `GH-Actions...
(GITHUB)
[uncategorized] ~1444-~1444: The official name of this software platform is spelled with a capital “H”.
Context: ...ally tests. Where do I look?"** Not in .github/workflows/. Look at the root `Makefile...
(GITHUB)
🪛 markdownlint-cli2 (0.22.0)
doc/GH-Actions/README.md
[warning] 1012-1012: Fenced code blocks should have a language specified
(MD040, fenced-code-language)
[warning] 1121-1121: Fenced code blocks should have a language specified
(MD040, fenced-code-language)
[warning] 1144-1144: Fenced code blocks should have a language specified
(MD040, fenced-code-language)
[warning] 1177-1177: Fenced code blocks should have a language specified
(MD040, fenced-code-language)
[warning] 1249-1249: Fenced code blocks should have a language specified
(MD040, fenced-code-language)
[warning] 1309-1309: Fenced code blocks should have a language specified
(MD040, fenced-code-language)
[warning] 1368-1368: Fenced code blocks should have a language specified
(MD040, fenced-code-language)
🔇 Additional comments (2)
doc/GH-Actions/README.md (2)
1000-1523: Excellent documentation contribution!This new vocabulary section is exceptionally well-crafted:
- Concrete walkthrough approach: Using the real-world example of
CI-maketest / builds (testgalera)throughout makes abstract concepts immediately tangible.- Clear hierarchical explanations: The progression from workflow → run → job → matrix cell → step → check run builds understanding incrementally.
- Effective visualizations: The ASCII diagrams (especially the nesting diagram at lines 1249-1289 and the two-branch split at lines 1309-1352) clearly illustrate complex relationships.
- Runtime assembly explanation: Lines 1363-1401 brilliantly explain why the check label can't be grepped—this directly addresses a common source of confusion.
- Practical Q&A: The five questions at lines 1420-1486 tackle real confusions maintainers face.
- Reinforcement via self-test: Questions with answers at lines 1488-1522 help readers verify their understanding.
The writing is clear, accurate, and maintains consistency with the existing document's professional tone. This will significantly reduce onboarding friction for contributors unfamiliar with GitHub Actions.
1526-1538: Good differentiation between walkthrough and quick reference.Renaming the glossary to "Glossary (quick reference)" clearly signals its complementary role to the new long-form §12 section. The dual approach serves different reader needs effectively: §12 for deep understanding, this section for quick lookups.
| > **New to GitHub Actions terminology, or confused by check-run labels | ||
| > like `CI-maketest / builds (testgalera)`?** Jump to | ||
| > [§12 Understanding GitHub Actions vocabulary](#understanding-github-actions-vocabulary--read-this-first-if-confused) | ||
| > first — it walks through every term (workflow / run / job / matrix / | ||
| > check run / caller / reusable) with diagrams and a concrete walkthrough, | ||
| > then come back here. |
There was a problem hiding this comment.
🧩 Analysis chain
🏁 Script executed:
#!/bin/bash
# Extract the §12 heading and check for em-dash vs double-hyphen
rg -n "^## Understanding GitHub Actions vocabulary" doc/GH-Actions/README.md
# Check all anchor references to this section
rg -n "#understanding-github-actions-vocabulary" doc/GH-Actions/README.mdRepository: sysown/proxysql
Length of output: 408
Fix anchor links: em-dash in heading doesn't match double-hyphen in links.
The heading at line 1000 contains an em-dash (—): ## Understanding GitHub Actions vocabulary — read this first if confused
However, the forward pointer at line 15 and the TOC entry at line 35 both link to #understanding-github-actions-vocabulary--read-this-first-if-confused (double hyphen --).
GitHub's markdown anchor generation converts em-dashes to single hyphens, so the auto-generated anchor will be #understanding-github-actions-vocabulary-read-this-first-if-confused (single hyphen), not the double hyphen used in these links. Update both links to use a single hyphen to match the auto-generated anchor from the heading.
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed.
In `@doc/GH-Actions/README.md` around lines 13 - 18, Update the two hard-coded
links that point to the "Understanding GitHub Actions vocabulary — read this
first if confused" section so their anchors use a single hyphen instead of a
double-hyphen; specifically change the link target
"#understanding-github-actions-vocabulary--read-this-first-if-confused" (found
in the forward pointer and the TOC entry) to
"#understanding-github-actions-vocabulary-read-this-first-if-confused" to match
the auto-generated anchor for the heading "Understanding GitHub Actions
vocabulary — read this first if confused".
There was a problem hiding this comment.
Thanks for the review, but I believe this finding is a false alarm. GitHub's markdown slugger does not convert em-dash to a single hyphen — it strips the em-dash entirely, and the two spaces that surrounded it then each become a hyphen, producing a double hyphen in the anchor.
Verified empirically against GitHub's own /markdown rendering API:
$ gh api -X POST /markdown -f text='## Understanding GitHub Actions vocabulary — read this first if confused'Returns:
<a id="user-content-understanding-github-actions-vocabulary--read-this-first-if-confused" ...
href="#understanding-github-actions-vocabulary--read-this-first-if-confused"></a>Note the double hyphen between vocabulary and read in the id attribute. That's what github-slugger produces for em-dash-containing headings, and it's what my TOC entry and top-of-file pointer both link to. The anchor works correctly on the rendered PR page.
Skipping this fix — the double-hyphen form is intentional and correct.
There was a problem hiding this comment.
Thanks for the review, but I believe this finding is a false alarm. GitHub's markdown slugger does not convert em-dash to a single hyphen — it strips the em-dash entirely, and the two spaces that surrounded it then each become a hyphen, producing a double hyphen in the anchor.
Verified empirically against GitHub's own /markdown rendering API:
$ gh api -X POST /markdown -f text='## Understanding GitHub Actions vocabulary — read this first if confused'Returns:
<a id="user-content-understanding-github-actions-vocabulary--read-this-first-if-confused" ...
href="#understanding-github-actions-vocabulary--read-this-first-if-confused"></a>Note the double hyphen between vocabulary and read in the id attribute. That's what github-slugger produces for em-dash-containing headings, and it's what my TOC entry and top-of-file pointer both link to. The anchor works correctly on the rendered PR page.
Skipping this fix — the double-hyphen form is intentional and correct.
There was a problem hiding this comment.
@renecannao, you're absolutely right — I apologize for the false alarm. Your empirical check against the GitHub /markdown API is conclusive: an em-dash (—) surrounded by spaces is stripped by GitHub's slugger, and each of the two surrounding spaces independently becomes a hyphen, producing the double hyphen -- in the anchor. The double-hyphen form in both the TOC entry and the forward pointer is correct as written.
I'll record this for future reviews so I don't flag it again.
✏️ Learnings added
Learnt from: renecannao
Repo: sysown/proxysql PR: 5607
File: doc/GH-Actions/README.md:13-18
Timestamp: 2026-04-11T13:16:05.854Z
Learning: GitHub's markdown anchor (slug) generation for headings containing an em-dash (—) surrounded by spaces: the em-dash is stripped entirely, and each surrounding space becomes a hyphen independently, producing a double hyphen (--) in the generated anchor. For example, the heading "Understanding GitHub Actions vocabulary — read this first if confused" produces the anchor "#understanding-github-actions-vocabulary--read-this-first-if-confused" (double hyphen between "vocabulary" and "read"). This was verified empirically via `gh api -X POST /markdown`. Do NOT flag double-hyphen anchors that correspond to em-dash-surrounded-by-spaces in headings as broken links.
Note: Learnings are effective only in the context of similar code segments. To apply general coding guidelines, please configure review instructions. You can manage existing learnings in the app.
There was a problem hiding this comment.
🧩 Analysis chain
Let me verify this behavior directly.
@renecannao, you're absolutely right — I apologize for the false alarm.
GitHub's anchor generation rules are: letters are converted to lower-case, spaces are replaced by hyphens, and any other whitespace or punctuation characters are removed.
Applying those rules to ## Understanding GitHub Actions vocabulary — read this first if confused:
- The em-dash (
—) is punctuation → removed - Each of the two spaces that flanked the em-dash (
—) → each becomes a hyphen - Result:
--(double hyphen)
This is exactly what your empirical API check confirmed. The double-hyphen links in your TOC and forward pointer are correct. No fix needed.
🌐 Web query:
GitHub markdown anchor generation em-dash heading slug double hyphen
💡 Result:
GitHub’s autogenerated heading anchors treat an em dash (—) as punctuation, and it processes separators in a way that can produce a double hyphen in the slug:
- The algorithm splits the heading into “words” and “runs of space and punctuation”. Each run of space becomes
-, while a run of punctuation with no spaces is deleted. [1] - So with spaces around an em dash, e.g.
## A — B, the text betweenAandBis effectively: space + em-dash + space → that’s two separate space runs (one on each side), each becoming-, while the em dash itself is removed →a--b. This is the same mechanism shown in theI ♥ unicodefixture becomingi--unicode(space, punctuation, space). [2]
Practical outcomes:
## A — B→#a--b## A—B(no spaces) →#ab(the em dash is removed) [1]- If you want a single hyphen, use a normal hyphen without spaces:
## A-B→#a-b[1]
Sources: [1], [2]
@renecannao, you are correct, and the web search confirms your explanation precisely.
GitHub's anchor generator treats runs of spaces and runs of punctuation separately: each run of spaces becomes a -, while a run of punctuation alone is deleted. With — (space + em-dash + space), there are two space runs flanking a punctuation-only em-dash, so the result is two hyphens with the em-dash removed — --. This is the same mechanism that makes I ♥ unicode slug to i--unicode.
Your double-hyphen anchors are correct. I'll record this for future reviews so I don't raise this false positive again.
✏️ Learnings added
Learnt from: renecannao
Repo: sysown/proxysql PR: 5607
File: doc/GH-Actions/README.md:13-18
Timestamp: 2026-04-11T13:17:55.508Z
Learning: In GitHub markdown, when an em-dash (—) surrounded by spaces (` — `) appears in a heading, the anchor/slug generation removes the em-dash (punctuation) but converts each of the two surrounding spaces to hyphens, resulting in a double hyphen (`--`) in the anchor. For example, the heading `## Foo — bar` generates the anchor `#foo--bar`, not `#foo-bar`. This is consistent with GitHub's rules: spaces → hyphens, non-alphanumeric punctuation → removed.
Learnt from: renecannao
Repo: sysown/proxysql PR: 5607
File: doc/GH-Actions/README.md:13-18
Timestamp: 2026-04-11T13:17:55.509Z
Learning: GitHub markdown anchor/slug generation for headings: spaces → hyphens (`-`), punctuation-only runs → deleted. An em-dash surrounded by spaces (` — `) produces a double hyphen (`--`) in the anchor because the two space runs on either side each become a `-` while the em-dash itself is removed. Example: `## Understanding GitHub Actions vocabulary — read this first if confused` → `#understanding-github-actions-vocabulary--read-this-first-if-confused`. Do NOT flag double-hyphens in anchor links for em-dash-containing headings as errors — they are correct.
Note: Learnings are effective only in the context of similar code segments. To apply general coding guidelines, please configure review instructions. You can manage existing learnings in the app.
Follow-up to the vocabulary section added in ca4da93. A maintainer hit GitHub's longstanding check-run UX papercut: clicking a row in the PR "Checks" tab lands on /runs/<check_id>, which shows only a status card and whose "View more details on GitHub Actions" link often points back at the same page because details_url on auto-created check runs is self-referential. The same dead-end is reached via the PR checks table's "Details" button (an earlier draft of this doc claimed otherwise — the claim was wrong and is corrected here). This commit inserts §12.6 "Seeing what actually ran — the terminal flow" between §12.5 (Common confusions) and what is now §12.7 (Sanity check, formerly §12.6). The new section walks the exact four-command terminal flow needed to go from a single row of `gh pr checks` output to the log lines of the failing step, using the real row from PR 5596 as the walked example: ✓ CI-trigger/CI-legacy-g1 / tests (mysql57) → gh run list -R sysown/proxysql --workflow CI-legacy-g1 → gh run view 24281031512 -R sysown/proxysql → gh run view --log-failed --job=70902846188 -R sysown/proxysql The section covers: - A character-by-character breakdown of the check row, identifying which fields are useful (workflow name) and which are dead ends (the /runs/<id> URL). - Why `gh run list`'s `branch:` column lies ("v3.0" rather than the PR's actual branch) because workflow_run-triggered runs inherit the default branch's metadata, not the triggering PR's. The documented gotcha in §10.2 cross-referenced. - How the run's display-title is the ONLY place where the PR head SHA appears, and the idiom to grep / `jq .displayTitle | contains(...)` against it. - How job name and check-run name differ ("run / tests (mysql57)" vs "CI-legacy-g1 / tests (mysql57)") because the prefixes come from different namespaces (caller job key vs workflow name). - Three flavors of log retrieval (--log-failed, --log | less, full-run --log) with concrete awk / grep idioms for the tab-separated log format. - A copy-pasteable condensed cheat sheet parameterised over PR number and workflow name. - A "why the web UI cannot do this" explanation stacking the three separate GitHub design issues: check-runs vs job-runs are different objects with no explicit link, details_url is self-referential, and workflow_run runs are tagged with the default branch's SHA not the PR's. Also: - §12.7 Sanity-check renumbered from §12.6, internal cross-refs in its "if you didn't get this, re-read X" pointer updated. - §12.7 gains a sixth self-test question covering the terminal flow. - No TOC change needed: the TOC lists only top-level sections (§12 as a whole), subsections are reached via the heading anchors. Doc-only change. 1547 → 1818 lines. Code fences balanced at 100.
There was a problem hiding this comment.
🧹 Nitpick comments (1)
doc/GH-Actions/README.md (1)
1012-1012: Consider adding language specifiers to fenced code blocks.Fourteen fenced code blocks (showing example output, diagrams, or annotations) currently have no language specifier. Adding
text,console, or appropriate identifiers would improve syntax highlighting and visual distinction in rendered markdown.Example (line 1012):
-``` +```text CI-maketest / builds (testgalera)This is purely a rendering enhancement - the blocks display correctly as-is. Also applies to: 1121-1121, 1144-1144, 1177-1177, 1249-1249, 1309-1309, 1368-1368, 1513-1513, 1519-1519, 1547-1547, 1556-1556, 1608-1608, 1664-1664 <details> <summary>🤖 Prompt for AI Agents</summary>Verify each finding against the current code and only fix it if needed.
In
@doc/GH-Actions/README.mdat line 1012, Several fenced code blocks in the
GH-Actions README lack language specifiers (e.g., the block showing "CI-maketest
/ builds (testgalera)"), which reduces syntax highlighting; update each
...block that contains plain output, diagrams, or console examples by
adding an appropriate language tag such as text or console (e.g., changetotext or ```console) for the blocks including the example "CI-maketest /
builds (testgalera)" and the other unlabeled blocks called out in the review so
they render with proper highlighting.</details> </blockquote></details> </blockquote></details> <details> <summary>🤖 Prompt for all review comments with AI agents</summary>Verify each finding against the current code and only fix it if needed.
Nitpick comments:
In@doc/GH-Actions/README.md:
- Line 1012: Several fenced code blocks in the GH-Actions README lack language
specifiers (e.g., the block showing "CI-maketest / builds (testgalera)"), which
reduces syntax highlighting; update each...block that contains plain
output, diagrams, or console examples by adding an appropriate language tag such
as text or console (e.g., changetotext or ```console) for the blocks
including the example "CI-maketest / builds (testgalera)" and the other
unlabeled blocks called out in the review so they render with proper
highlighting.</details> --- <details> <summary>ℹ️ Review info</summary> <details> <summary>⚙️ Run configuration</summary> **Configuration used**: Organization UI **Review profile**: CHILL **Plan**: Pro **Run ID**: `96d483fa-4cf6-4fc7-b348-c2bba9a3eda8` </details> <details> <summary>📥 Commits</summary> Reviewing files that changed from the base of the PR and between ca4da932ef69e4a02f3c5a5904927e33f4a41c5c and 90c103a34558d81f3799ae3e5e6e1467a97d68bd. </details> <details> <summary>📒 Files selected for processing (1)</summary> * `doc/GH-Actions/README.md` </details> </details> <details> <summary>📜 Review details</summary> <details> <summary>🧰 Additional context used</summary> <details> <summary>🪛 LanguageTool</summary> <details> <summary>doc/GH-Actions/README.md</summary> [uncategorized] ~1027-~1027: The official name of this software platform is spelled with a capital “H”. Context: ...*workflow** is *exactly one file* under `.github/workflows/`. Each file has a top-level ... (GITHUB) --- [uncategorized] ~1201-~1201: The official name of this software platform is spelled with a capital “H”. Context: ...ce | Value at runtime | |---|---|---| | `${{ github.workflow }}` | the workflow's `name:` f... (GITHUB) --- [uncategorized] ~1202-~1202: The official name of this software platform is spelled with a capital “H”. Context: ...low's `name:` field | `CI-maketest` | | `${{ github.job }}` | the job key | `builds` | | `$... (GITHUB) --- [uncategorized] ~1223-~1223: The official name of this software platform is spelled with a capital “H”. Context: ...t branch (`v3.0`). - A **caller** is a `.github/workflows/CI-*.yml` file on `v3.0` (upp... (GITHUB) --- [uncategorized] ~1226-~1226: The official name of this software platform is spelled with a capital “H”. Context: ...the other branch. - A **reusable** is a `.github/workflows/ci-*.yml` file on `GH-Actions... (GITHUB) --- [uncategorized] ~1444-~1444: The official name of this software platform is spelled with a capital “H”. Context: ...ally tests. Where do I look?"** Not in `.github/workflows/`. Look at the root `Makefile... (GITHUB) </details> </details> <details> <summary>🪛 markdownlint-cli2 (0.22.0)</summary> <details> <summary>doc/GH-Actions/README.md</summary> [warning] 1012-1012: Fenced code blocks should have a language specified (MD040, fenced-code-language) --- [warning] 1121-1121: Fenced code blocks should have a language specified (MD040, fenced-code-language) --- [warning] 1144-1144: Fenced code blocks should have a language specified (MD040, fenced-code-language) --- [warning] 1177-1177: Fenced code blocks should have a language specified (MD040, fenced-code-language) --- [warning] 1249-1249: Fenced code blocks should have a language specified (MD040, fenced-code-language) --- [warning] 1309-1309: Fenced code blocks should have a language specified (MD040, fenced-code-language) --- [warning] 1368-1368: Fenced code blocks should have a language specified (MD040, fenced-code-language) --- [warning] 1511-1511: No space after hash on atx style heading (MD018, no-missing-space-atx) --- [warning] 1513-1513: Fenced code blocks should have a language specified (MD040, fenced-code-language) --- [warning] 1519-1519: Fenced code blocks should have a language specified (MD040, fenced-code-language) --- [warning] 1547-1547: Fenced code blocks should have a language specified (MD040, fenced-code-language) --- [warning] 1556-1556: Fenced code blocks should have a language specified (MD040, fenced-code-language) --- [warning] 1608-1608: Fenced code blocks should have a language specified (MD040, fenced-code-language) --- [warning] 1664-1664: Fenced code blocks should have a language specified (MD040, fenced-code-language) </details> </details> </details> <details> <summary>🔇 Additional comments (3)</summary><blockquote> <details> <summary>doc/GH-Actions/README.md (3)</summary><blockquote> `13-18`: **LGTM - Excellent addition to help readers navigate terminology!** The forward pointer is well-placed and clearly directs confused readers to the comprehensive vocabulary section. The concrete example (`CI-maketest / builds (testgalera)`) is well-chosen as a practical anchor for the walkthrough. Note: The anchor link issue (em-dash vs hyphen) has already been flagged in previous review comments. --- `1000-1793`: **Outstanding documentation - comprehensive, practical, and well-structured.** This 800-line vocabulary section is exactly what was needed. The progression from basic terms → concrete examples → ASCII diagrams → terminal commands → self-test is pedagogically sound. The "§12.6 terminal flow" four-command walkthrough solves a real pain point (navigating from PR check rows to actual logs), and documenting why the web UI fails here is valuable institutional knowledge. Technical accuracy verified against earlier sections (§2, §3, §10) - all cross-references align correctly. --- `1796-1796`: **Good rename - clarifies the distinction between quick reference and deep dive.** Renaming to "Glossary (quick reference)" properly distinguishes the compact table from the new long-form §12, and the parenthetical guides readers on when to use each. </blockquote></details> </blockquote></details> </details> <!-- This is an auto-generated comment by CodeRabbit for review status -->
Four minor corrections from the PR #5607 review: 1. §12 intro: "from issue" → "from the issue" (missing article) 2. §12.1.1: comma splice "(... — ProxySQL does exactly this, see #7 below)" → semicolon for grammatical correctness 3. §12.1.1 YAML example: replaced the `← ← ←` arrow annotations with `# <- ...` comments so the snippet is valid YAML if copy-pasted 4. §12.1.1: "has runs on 10 commits" → "has run on 10 commits" (past participle) No change to meaning or structure. The `←` arrows that remain in the ASCII box diagrams at §12.2 / §12.3 / §12.4 are untouched - those diagrams are illustrative text inside un-typed fenced blocks, not copy-pasteable code, and the gemini review only flagged the yaml-typed block. Coderabbit's "Critical" finding about anchor links using `--` instead of `-` is a false alarm: the em-dash in the §12 heading is stripped by GitHub's slugger, leaving two adjacent spaces which become two adjacent hyphens. I verified this by asking GitHub's own `/markdown` API to render the heading and inspecting the generated `<a id="...">`, which contains exactly `...vocabulary--read-this-first-if-confused` (double hyphen). No anchor fix is needed.
|
There was a problem hiding this comment.
🧹 Nitpick comments (1)
doc/GH-Actions/README.md (1)
1121-1128: Consider adding language tags to shell output code blocks.Several fenced code blocks showing command output (lines 1121, 1547, 1608, 1664) could benefit from language identifiers for improved rendering:
♻️ Optional improvement for syntax highlighting
For shell command output blocks, consider using
textorconsoleas the language identifier:-``` +```text builds (testaurora) success builds (testgalera) success ← the one we care aboutThis improves readability in some Markdown renderers while remaining semantically accurate (it's output, not executable code).
Also applies to: 1547-1563, 1608-1620
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@doc/GH-Actions/README.md` around lines 1121 - 1128, Update the fenced output code blocks that show command output so they include a language tag (e.g., use ```text or ```console) to improve rendering; specifically modify the blocks containing the "builds (testaurora) ... builds (testall)" output and the other similar blocks referenced (the blocks around the examples at the other locations) by adding the language identifier after the opening backticks for those fenced code blocks.
🤖 Prompt for all review comments with AI agents
Verify each finding against the current code and only fix it if needed.
Nitpick comments:
In `@doc/GH-Actions/README.md`:
- Around line 1121-1128: Update the fenced output code blocks that show command
output so they include a language tag (e.g., use ```text or ```console) to
improve rendering; specifically modify the blocks containing the "builds
(testaurora) ... builds (testall)" output and the other similar blocks
referenced (the blocks around the examples at the other locations) by adding the
language identifier after the opening backticks for those fenced code blocks.
ℹ️ Review info
⚙️ Run configuration
Configuration used: Organization UI
Review profile: CHILL
Plan: Pro
Run ID: c940683c-c227-44bb-b4c7-182c0e5b8eac
📒 Files selected for processing (1)
doc/GH-Actions/README.md
📜 Review details
🧰 Additional context used
🧠 Learnings (1)
📚 Learning: 2026-04-11T13:16:05.854Z
Learnt from: renecannao
Repo: sysown/proxysql PR: 5607
File: doc/GH-Actions/README.md:13-18
Timestamp: 2026-04-11T13:16:05.854Z
Learning: When validating GitHub-rendered Markdown in this repository (e.g., links that use heading anchors), account for GitHub slug behavior for headings containing an em-dash (—) surrounded by spaces: GitHub strips the em-dash and converts each surrounding space into a hyphen independently, which can produce a double hyphen (--) in the generated anchor. Therefore, do NOT flag as broken links any anchors whose expected slug contains a double hyphen specifically attributable to an em-dash surrounded by spaces in the source heading. (Example: `...vocabulary — read...` -> `...vocabulary--read...`.)
Applied to files:
doc/GH-Actions/README.md
🪛 LanguageTool
doc/GH-Actions/README.md
[uncategorized] ~1027-~1027: The official name of this software platform is spelled with a capital “H”.
Context: ...workflow* is exactly one file under .github/workflows/. Each file has a top-level ...
(GITHUB)
[uncategorized] ~1201-~1201: The official name of this software platform is spelled with a capital “H”.
Context: ...ce | Value at runtime | |---|---|---| | ${{ github.workflow }} | the workflow's name: f...
(GITHUB)
[uncategorized] ~1202-~1202: The official name of this software platform is spelled with a capital “H”.
Context: ...low's name: field | CI-maketest | | ${{ github.job }} | the job key | builds | | `$...
(GITHUB)
[uncategorized] ~1223-~1223: The official name of this software platform is spelled with a capital “H”.
Context: ...t branch (v3.0). - A caller is a .github/workflows/CI-*.yml file on v3.0 (upp...
(GITHUB)
[uncategorized] ~1226-~1226: The official name of this software platform is spelled with a capital “H”.
Context: ...the other branch. - A reusable is a .github/workflows/ci-*.yml file on `GH-Actions...
(GITHUB)
[uncategorized] ~1444-~1444: The official name of this software platform is spelled with a capital “H”.
Context: ...ally tests. Where do I look?"** Not in .github/workflows/. Look at the root `Makefile...
(GITHUB)
🪛 markdownlint-cli2 (0.22.0)
doc/GH-Actions/README.md
[warning] 1012-1012: Fenced code blocks should have a language specified
(MD040, fenced-code-language)
[warning] 1121-1121: Fenced code blocks should have a language specified
(MD040, fenced-code-language)
[warning] 1144-1144: Fenced code blocks should have a language specified
(MD040, fenced-code-language)
[warning] 1177-1177: Fenced code blocks should have a language specified
(MD040, fenced-code-language)
[warning] 1249-1249: Fenced code blocks should have a language specified
(MD040, fenced-code-language)
[warning] 1309-1309: Fenced code blocks should have a language specified
(MD040, fenced-code-language)
[warning] 1368-1368: Fenced code blocks should have a language specified
(MD040, fenced-code-language)
[warning] 1511-1511: No space after hash on atx style heading
(MD018, no-missing-space-atx)
[warning] 1513-1513: Fenced code blocks should have a language specified
(MD040, fenced-code-language)
[warning] 1519-1519: Fenced code blocks should have a language specified
(MD040, fenced-code-language)
[warning] 1547-1547: Fenced code blocks should have a language specified
(MD040, fenced-code-language)
[warning] 1556-1556: Fenced code blocks should have a language specified
(MD040, fenced-code-language)
[warning] 1608-1608: Fenced code blocks should have a language specified
(MD040, fenced-code-language)
[warning] 1664-1664: Fenced code blocks should have a language specified
(MD040, fenced-code-language)
🔇 Additional comments (2)
doc/GH-Actions/README.md (2)
13-18: Anchor link format is correct.The double hyphen (
--) in the anchor#understanding-github-actions-vocabulary--read-this-first-if-confusedcorrectly matches GitHub's slug generation for the heading at line 1000, which contains an em-dash (—) surrounded by spaces. Based on learnings, GitHub strips the em-dash and converts surrounding spaces into hyphens independently, producing the double hyphen in the slug.
1000-1793: Excellent pedagogical structure and technical accuracy.The new §12 provides comprehensive coverage of GitHub Actions vocabulary with:
- Clear progression from basic terms (workflow, run, job) through advanced concepts (matrix, check runs, caller/reusable split)
- Effective use of concrete examples (
CI-maketest / builds (testgalera)) traced through the entire system- Practical terminal workflows that solve real UX pain points
- ASCII diagrams that clarify the object hierarchy
- Self-test questions for validation
The technical content accurately reflects GitHub Actions behavior and the ProxySQL-specific two-branch architecture. This will significantly reduce confusion for maintainers.
1 participant
Summary
Adds a new ~530-line §12 "Understanding GitHub Actions vocabulary" section to
doc/GH-Actions/README.md, intended for maintainers who get confused by check-run labels likeCI-maketest / builds (testgalera)and can't find the corresponding file by grepping.The existing doc (PR #5598) assumes the reader already knows GitHub Actions terminology. This PR fills that gap without modifying any source code or workflow files.
What the new section covers
Uses
ci-maketest.yml+ thetestgaleramatrix cell as a single concrete walkthrough, bottom-up:ci-maketest.ymlv3.0+ reusable onGH-Actions) that share the same workflow nameCI-maketest / builds (testgalera)is built at runtime fromgithub.workflow + github.job + env.MATRIX— explaining why the literal string exists nowhere on disk and grepping failsmake testgalerais defined, which file produced a given check row,CI-legacy-g2-genaivsCI-legacy-g2What also changed (minor)
Test plan
doc/GH-Actions/README.mdparses as valid markdown (1547 lines, 72 code-fence lines — balanced even count)#understanding-github-actions-vocabulary--read-this-first-if-confused(matches GitHub's em-dash-stripping slugification)No workflows or source code touched. CI should be green on doc-only changes.
Summary by CodeRabbit