branch-docs-sync

Objective

Update and maintain documentation consistency by analyzing recent git commits and applying surgical updates across developer notes, user-facing site content, and system manual pages.

Workflow

1. Research & Analysis

• Identify Range: Determine the set of commits to analyze. If not specified, analyze all commits unique to the current feature branch.
• Extract Changes: Use git log -n 10 and git show <sha> for key commits to identify:
  • Architectural Refactors: Renames of subsystems, directories, or core libraries.
  • New Features: Added RIB statements, new shaders, or expanded language bindings.
  • Breaking Changes: Changed environment variables, tool names, or API signatures.
  • Fixed Bugs: Resolved issues that require updating the status in BUGS.md or DEVNOTES.md.

2. Update Developer Notes (DEVNOTES.md & DEVNOTES_DETAILS/**)

• Project Status: Update the "Project Status" table in the main DEVNOTES.md.
• Major Refactors: Add a bullet point to the "Recent Major Refactors" section summarizing systemic changes.
• Detail Files:
  • Update OSHADER_UPDATES.md for compiler or shading language changes.
  • Update BINDINGS_GUIDE.md for Python/Lua/C++ interface changes.
  • Update FRAMEBUFFER_GUIDE.md for display driver or IPC changes.
  • Create new detail files (e.g., RIB_GUIDE.md) for significant new subsystems.

3. Update Site Documentation (docs/site/content/**)

• Branding & Consistency: Perform batch updates for project name (e.g., "Pixie" -> "openRender") or environment variables (e.g., PIXIEHOME -> ORENDERHOME).
• URL Routing: Ensure internal links and file names match the new branding or tool names.
• Tooling References: Update command-line examples to reflect tool renames (e.g., sdrinfo -> rsloinfo).

4. Update Distribution & Release Files

• README.md: Refresh the directory structure overview and installation requirements.
• INSTALL_ARTIFACTS.md: Update the list of installed binaries and libraries.
• NEWS.md & ChangeLog.md: Add dated entries summarizing the new capabilities and refactors.
• Build Templates: Update Homebrew (.rb.template) or RPM (.spec) files to ensure they package the new artifacts.

5. Update Manual Pages (man/**)

• Rename: If a tool has been renamed, rename the corresponding .1 file.
• Content: Update the usage synopsis and descriptions to match the current implementation.

Key Rules

• Preserve Case: When performing batch renames (e.g., "pixie" -> "openrender"), respect the casing of the original string.
• Surgical Edits: Use targeted replace calls with enough context to avoid ambiguous matches.
• Audit: After updates, run a grep_search for the old terms (e.g., "sdr", "Pixie") to ensure no stale references remain in active documentation.
• Confirmation: Present a summary of all documentation changes to the user for final approval.

Verification

• Validate that all internal markdown links are functional.
• Ensure the ChangeLog.md follows the project's established format.
• Verify that the INSTALL_ARTIFACTS.md accurately reflects the current CMakeLists.txt configuration.