Skip to content

ci: document and gate product exit codes in README tables - #150

Merged
TMHSDigital merged 2 commits into
mainfrom
feat/exit-code-readme-gate
Sep 13, 2026
Merged

TMHSDigital merged 2 commits into
mainfrom
feat/exit-code-readme-gate

Conversation

@TMHSDigital

Copy link
Copy Markdown
Owner

Summary

  • 3a (50a26c7): headless-batch-script-template README now has a CONTRIBUTING-shaped exit table for 0, argparse/no mesh 2, modifier 3, glTF 4. Script unchanged. extension-addon-template has no sys.exit and needs nothing. ai-asset-pipeline-template already had a table.
  • 3b (b1c1268): tests/check_exit_code_readme.py, wired blocking in validate.yml. AST only. No exemption list.
  • Closes ci: report-mode check that every nonzero exit is documented in its own script README #138 (blocking from day one, not report-mode).

Detection: integer return N plus literal sys.exit(N) in examples/, templates/, showcase/. sys.exit(main()) / sys.exit(exit_code) after exit_code = main() are harness pass-through. sys.exit(1) in except is FATAL. README check is entry-point files only (if __name__ == "__main__"). Helpers such as gallery_framing.py are still scanned for unanalyzable sys.exit.

No non-literal product exits in the tree. No skip file.

Gate-failure proof (verbatim)

===== 1-undocumented-return exit=1 =====
ERROR: examples/bmesh-gear/bmesh_gear.py:218: return/exit 99 is not in the examples/bmesh-gear/README.md exit table

===== 2-unanalyzable-exit exit=1 =====
ERROR: examples/bmesh-gear/bmesh_gear.py:223: unanalyzable exit code: sys.exit(undocumented)

===== 3-fatal-guard-clean exit=0 =====
exit-code README checks passed.

===== 4-kit-exit-10-undocumented exit=1 =====
ERROR: examples/modular-kit-snap/modular_kit_snap.py:629: return/exit 10 is not in the examples/modular-kit-snap/README.md exit table

===== 5-clean-tree exit=0 =====
exit-code README checks passed.

Canaries were applied, observed, and deleted. Working tree after #5 matches HEAD. Canary 3 is the same checker run against the tree that still has the normal __main__ sys.exit(1) FATAL wrappers (e.g. bmesh-gear).

Test plan

  • Validate (new checker step green)
  • Blender 5.2 LTS smoke
  • Blender 4.5 LTS smoke
  • Socket Security
  • Drift check

No example behavior change — needs-5.1 not applied.

Live run: canaries above. Inspection: template script.py untouched; validate.yml step next to check_import_export_rules.py.

TMHSDigital and others added 2 commits September 13, 2026 14:00
The checker in the next commit covers templates/. Product codes lived in prose only, so a missing-table file would fail the gate.

Signed-off-by: TMHSDigital <154358121+TMHSDigital@users.noreply.github.com>
Co-authored-by: Cursor <cursoragent@cursor.com>
AST collects return N and literal sys.exit(N) on examples, templates, and showcase. sys.exit(main()) and the FATAL except wrapper are not product codes. Blocking from day one; no skip list. Closes #138.

Signed-off-by: TMHSDigital <154358121+TMHSDigital@users.noreply.github.com>
Co-authored-by: Cursor <cursoragent@cursor.com>
@github-actions github-actions Bot added templates documentation Improvements or additions to documentation ci labels Sep 13, 2026
@TMHSDigital
TMHSDigital merged commit d2780a8 into main Sep 13, 2026
11 checks passed
@TMHSDigital
TMHSDigital deleted the feat/exit-code-readme-gate branch September 13, 2026 18:10
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

ci documentation Improvements or additions to documentation templates

Projects

None yet

Development

Successfully merging this pull request may close these issues.

ci: report-mode check that every nonzero exit is documented in its own script README

1 participant