Skip to content

Docs Issue Sync (gh CLI)

Use scripts/sync_docs_issues.sh to mirror actionable TODOs embedded inside documentation only when the work item is documentation-focused (navigation, structure, spelling, content gaps).

For regular code bugs or feature changes, create a GitHub Issue directly with gh issue create (see "Direct Issue Creation" below) instead of adding a standalone local markdown file. This keeps the repo clean and avoids orphaned fix docs.

Embedded Issue Markers (Docs-Specific)

Mark docs-related issues inline in markdown with a comment marker:

<!-- GH-ISSUE: title=Fix nav for docs; labels=docs|enhancement; assignees=ChrisTutorials; complete=false; example=true -->

Fields:

  • title: Issue title (required)
  • labels: Pipe-separated labels (optional)
  • assignees: Pipe- or comma-separated usernames (optional)
  • complete: true|false (optional). If true, the script auto-closes the issue after creation/update.

Run sync:

  • gh auth login # once
  • bash scripts/sync_docs_issues.sh

Output:

  • Report: docs_site/reports/docs_issue_sync_report.md

Notes:

  • Existing issues matched by exact title (prevents duplicates).
  • Set GH_REPO=owner/name to override auto-detection.
  • Use Git Bash on Windows; PowerShell users should invoke via Git Bash.

Direct Issue Creation (Preferred For Code Bugs / Runtime Behavior)

Skip creating a local docs_site/docs/fixes/*.md file for runtime or API bugs (e.g. dependency injection gaps, rule lifecycle problems). Instead, open the issue directly:

Example (bug in placement rule initialization):

gh issue create \
    --title "Placement rules from placeable instances are not initialized (injection gap)" \
    --body "When calling PlacementManager.try_setup() the rules supplied only from the placeable resource are not run through initialize(logger). Only base container rules are initialized during PlacementManager.initialize(). This causes _logger to be null in validate_condition for custom placeable-level rules. Expected: all combined rules share identical lifecycle. Proposed fix: either unify initialize+setup into a single prepare() or ensure initialize() runs on any non-initialized rule inside try_setup() before validator.setup(). Acceptance: no rule validates with null logger; new unit test passes." \
    --label bug --label rules --label placement --label api

Guidelines:

  • Keep body concise: Summary, Impact, Expected vs Actual, Proposed Fix (optional).
  • Use labels to categorize (e.g. bug, feature, docs, api).
  • Reference related test names when a failing test documents the bug.
  • If a unit test already exists capturing the failure, mention it instead of writing a separate fix markdown doc.

When To Still Add a Fix Doc

Add a versioned fix / migration doc only when:

  • There is a user-facing API change needing upgrade notes.
  • You deprecate or rename public methods (e.g. migrating from initialize()+setup() to prepare()).
  • Complex refactors require extended rationale beyond typical issue length.

Otherwise prefer: Unit Test + GitHub Issue.

Test-Driven Bug Documentation

For lifecycle or injection gaps, create a failing GdUnit test named <area>_<short_description>_test.gd with an assertion message linking the issue title. After the fix, the test should pass without changing the assertion text (ensures traceability).

Migration Note Template (If API Unification Chosen)

If unifying rule lifecycle methods:

  1. Introduce prepare(p_logger, p_params).
  2. Internally call existing initialize() and setup() while emitting a deprecation warning once.
  3. Update managers/validators to call prepare() for all rules (placeable + base) before validation.
  4. Add CHANGELOG entry under "Unification" with old->new usage snippet.
  5. Remove direct initialize() calls after deprecation window.

Quick Reference

Scenario Use Embedded Marker Create Direct Issue Add Fix Doc
Typos / docs nav Yes Optional No
Injection / lifecycle bug No Yes Only if API change
API deprecation Optional Yes Yes
Refactor internals (no API change) No Yes No

This policy prevents proliferation of stale fix markdown files and keeps code-facing bugs tracked where contributors expect them: GitHub Issues.