Summary
When a new extension is added to release_build_versions.txt (i.e. it becomes part of the automated build and release pipeline), there is no automated check to ensure it also gets a corresponding entry in the documentation at docs/index.md and a dedicated docs/<extension>.md page. This can lead to extensions being built and released but not discoverable via https://flatcar.github.io/sysext-bakery/.
Proposal
Add a GitHub Actions workflow that runs whenever release_build_versions.txt is pushed to main. The workflow would:
- Parse the extension names from
release_build_versions.txt.
- Parse the extension names listed in the table in
docs/index.md.
- For each extension present in the build list but absent from the docs index, open a GitHub issue — if an open issue for that extension does not already exist.
Issue deduplication
To avoid duplicate issues, each opened issue should use a consistent title pattern (e.g. docs: add documentation for <extension> sysext) and/or a label (e.g. missing-docs). Before opening, the workflow should search for existing open issues matching the extension name and that label.
Issue content
Each opened issue should include:
- The extension name
- A note that it was detected as present in
release_build_versions.txt but missing from docs/index.md
- A checklist of what's needed:
Scope
This workflow intentionally does not auto-generate documentation or open PRs with draft docs, since each extension's docs page requires human-written content (upstream project description and link, extension-specific configuration notes, and a tested Butane snippet).
The reverse case — an extension removed from release_build_versions.txt that still has docs listing it as "released" — is out of scope for now but could be added later.
Existing gap
For reference, there are extensions today that appear in release_build_versions.txt but are not listed in the docs/index.md table (e.g. btop, tilde). This workflow would have caught those.
Summary
When a new extension is added to
release_build_versions.txt(i.e. it becomes part of the automated build and release pipeline), there is no automated check to ensure it also gets a corresponding entry in the documentation atdocs/index.mdand a dedicateddocs/<extension>.mdpage. This can lead to extensions being built and released but not discoverable via https://flatcar.github.io/sysext-bakery/.Proposal
Add a GitHub Actions workflow that runs whenever
release_build_versions.txtis pushed tomain. The workflow would:release_build_versions.txt.docs/index.md.Issue deduplication
To avoid duplicate issues, each opened issue should use a consistent title pattern (e.g.
docs: add documentation for <extension> sysext) and/or a label (e.g.missing-docs). Before opening, the workflow should search for existing open issues matching the extension name and that label.Issue content
Each opened issue should include:
release_build_versions.txtbut missing fromdocs/index.mddocs/index.mddocs/<extension>.mdwith a description, upstream project link, and a Butane configuration snippethttps://github.com/flatcar/sysext-bakery/releases/tag/<extension>Scope
This workflow intentionally does not auto-generate documentation or open PRs with draft docs, since each extension's docs page requires human-written content (upstream project description and link, extension-specific configuration notes, and a tested Butane snippet).
The reverse case — an extension removed from
release_build_versions.txtthat still has docs listing it as "released" — is out of scope for now but could be added later.Existing gap
For reference, there are extensions today that appear in
release_build_versions.txtbut are not listed in thedocs/index.mdtable (e.g.btop,tilde). This workflow would have caught those.