Skip to content

Conversation

@flyingrobots
Copy link
Owner

This hotfix makes the docs rollup CI check deterministic and future-proof.

Why

  • Earlier versions of the rollup generator emitted a timestamp line (e.g., 'Generated: …'). Regenerating in CI would always change that line, causing the rollup check to fail even when docs were up to date.

What changed

  • CI workflow (): compare normalized rollups — strip any lines beginning with from both the committed and regenerated files before diffing. Current generator already writes a stable header; this change prevents false negatives on older branches.
  • Docs: recorded the hotfix in and per Docs Guard.
  • Rollup: regenerated with the current generator (no functional content change).

Scope

  • No runtime changes. Tests/lints all green locally on push.

Follow‑ups (optional)

  • Consider adding a pre-commit normalization helper if we ever reintroduce variable metadata.

- CI: normalize 'Generated:' header lines before diff to avoid false failures on older branches
- Docs: record hotfix in execution plan + decision log
- Rollup: regenerated (no functional changes)
@coderabbitai
Copy link
Contributor

coderabbitai bot commented Nov 2, 2025

Warning

Rate limit exceeded

@flyingrobots has exceeded the limit for the number of commits or files that can be reviewed per hour. Please wait 12 minutes and 3 seconds before requesting another review.

⌛ How to resolve this issue?

After the wait time has elapsed, a review can be triggered using the @coderabbitai review command as a PR comment. Alternatively, push new commits to this PR.

We recommend that you space out your commits to avoid hitting the rate limit.

🚦 How do rate limits work?

CodeRabbit enforces hourly rate limits for each developer per organization.

Our paid plans have higher rate limits than the trial, open-source and free plans. In all cases, we re-allow further reviews after a brief timeout.

Please see our FAQ for further information.

📥 Commits

Reviewing files that changed from the base of the PR and between e509efd and fc60fb9.

📒 Files selected for processing (1)
  • .github/workflows/echo-total-check.yml (1 hunks)

Summary by CodeRabbit

  • Chores
    • Enhanced CI workflow robustness for documentation consistency checks.
    • Updated internal documentation and decision log with infrastructure improvement notes.

Walkthrough

Replaces the previous direct git-diff in the docs rollup CI with a capture‑regenerate‑normalize‑compare flow that normalizes header “Generated:” variants in the top header block before diffing. Adds corresponding hotfix entries to decision-log, echo-total, and execution-plan docs.

Changes

Cohort / File(s) Change Summary
CI Workflow
\.github/workflows/echo-total-check\.yml
Rewrote diff step: create temporary workspace, save HEAD docs/echo-total.md, regenerate docs/echo-total.md, normalize header region (remove/normalize lines like Generated:, generated at:, Generated by: up to first blank line) for both files, compare normalized outputs, show diff and fail with annotation if differences remain. Removed prior direct git diff invocation.
Documentation entries
docs/decision-log.md, docs/echo-total.md, docs/execution-plan.md
Added two 2025-11-02 hotfix entries describing the deterministic rollup check and tighter header normalization plus annotation guidance. Content documents context, decision, and consequence for the CI change.

Sequence Diagram(s)

sequenceDiagram
    autonumber
    participant GH as GitHub Actions
    participant Workspace as Temp Workspace
    participant Make as `make echo-total`
    participant Norm as Header Normalizer
    participant Diff as Normalized Comparator

    GH->>Workspace: create temp dir
    GH->>Workspace: copy HEAD `docs/echo-total.md` -> `old.md`
    GH->>Make: run `make echo-total` (writes `docs/echo-total.md`)
    GH->>Workspace: copy regenerated `docs/echo-total.md` -> `new.md`
    Workspace->>Norm: normalize header of `old.md` -> `old.norm.md`
    Workspace->>Norm: normalize header of `new.md` -> `new.norm.md`
    Norm->>Diff: compare `old.norm.md` vs `new.norm.md`
    alt files identical
        Diff->>GH: exit success
    else differences found
        Diff->>GH: emit annotated failure, print unified diff, exit failure
    end
Loading

Estimated code review effort

🎯 2 (Simple) | ⏱️ ~10 minutes

  • Pay attention to the header-normalization regex/grep to ensure it only affects the top header block and handles case/whitespace variants.
  • Verify temporary workspace creation, file permissions, and that GitHub Actions annotations are properly formed and escaped.

Possibly related PRs

Poem

Timestamps danced and broke the test,
Headers swayed and failed the quest.
Strip the noise from the first few lines,
Diff what's real, ignore the signs.
CI sleeps now — deterministic rest.

Pre-merge checks and finishing touches

❌ Failed checks (1 warning)
Check name Status Explanation Resolution
Docstring Coverage ⚠️ Warning Docstring coverage is 0.00% which is insufficient. The required threshold is 80.00%. You can run @coderabbitai generate docstrings to improve docstring coverage.
✅ Passed checks (2 passed)
Check name Status Explanation
Title Check ✅ Passed The title "hotfix(ci/docs): deterministic docs rollup check" directly and precisely captures the primary change across the pull request. The changes in .github/workflows/echo-total-check.yml implement exactly what the title describes—a deterministic rollup check by normalizing header-generated lines. The supporting documentation updates in docs/decision-log.md, docs/echo-total.md, and docs/execution-plan.md further reinforce this core objective. The title is concise, free of noise, and unambiguously communicates the most critical change from the author's perspective.
Description Check ✅ Passed The description directly addresses the changeset across all affected areas: it explains the problem (timestamp line causing false CI failures), describes the solution (CI workflow normalization logic), accounts for all documentation updates per Docs Guard, and explicitly states the scope boundaries (no runtime changes, tests pass). The narrative establishes clear cause-and-effect reasoning that aligns with the raw_summary and file-level changes, leaving no ambiguity about what was changed and why.

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.

❤️ Share

Comment @coderabbitai help to get the list of available commands and usage tips.

Copy link
Contributor

@coderabbitai coderabbitai bot left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Actionable comments posted: 1

📜 Review details

Configuration used: CodeRabbit UI

Review profile: ASSERTIVE

Plan: Pro

📥 Commits

Reviewing files that changed from the base of the PR and between 48a3381 and ef0926e.

📒 Files selected for processing (4)
  • .github/workflows/echo-total-check.yml (1 hunks)
  • docs/decision-log.md (1 hunks)
  • docs/echo-total.md (2 hunks)
  • docs/execution-plan.md (1 hunks)
🧰 Additional context used
🪛 LanguageTool
docs/decision-log.md

[uncategorized] ~165-~165: The official name of this software platform is spelled with a capital “H”.
Context: ...fto always differ. - Decision: Update.github/workflows/echo-total-check.yml` to norm...

(GITHUB)

⏰ Context from checks skipped due to timeout of 90000ms. You can increase the timeout in your CodeRabbit configuration to a maximum of 15 minutes (900000ms). (1)
  • GitHub Check: Security Audit
🔇 Additional comments (4)
docs/echo-total.md (2)

532-535: Docs guard entry is clear and scoped.

Entry explains normalization and aligns with the workflow change. No action needed.


703-708: Hotfix narrative matches CI behavior.

Context/Decision/Consequence read correctly and reference the exact workflow path. Good.

docs/execution-plan.md (1)

305-307: Execution plan note LGTM.

Concise, dated (2025-11-02), and consistent with Decision Log. Ship it.

docs/decision-log.md (1)

161-166: Decision entry is precise and reproducible.

Date, context, decision, and consequence are explicit and align with the workflow diff. No changes needed.

coderabbitai[bot]
coderabbitai bot previously approved these changes Nov 2, 2025
…otation

- Normalize only header-region lines matching ^\s*[Gg]enerated(\s*(:|at:|by:))? to avoid deleting arbitrary content
- Add GitHub Actions ::error annotation for clearer diagnostics
- Log follow-up in execution plan and decision log
- Regenerate rollup
Copy link
Contributor

@coderabbitai coderabbitai bot left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Actionable comments posted: 3

📜 Review details

Configuration used: CodeRabbit UI

Review profile: ASSERTIVE

Plan: Pro

📥 Commits

Reviewing files that changed from the base of the PR and between ef0926e and e509efd.

📒 Files selected for processing (4)
  • .github/workflows/echo-total-check.yml (1 hunks)
  • docs/decision-log.md (1 hunks)
  • docs/echo-total.md (2 hunks)
  • docs/execution-plan.md (1 hunks)
🧰 Additional context used
🪛 GitHub Actions: Docs Rollup Check
docs/echo-total.md

[error] 1-1: docs/echo-total.md is out of date. Run 'make echo-total' (or scripts/gen-echo-total.sh) and commit the result.

🪛 LanguageTool
docs/decision-log.md

[uncategorized] ~165-~165: The official name of this software platform is spelled with a capital “H”.
Context: ...fto always differ. - Decision: Update.github/workflows/echo-total-check.yml` to norm...

(GITHUB)

⏰ Context from checks skipped due to timeout of 90000ms. You can increase the timeout in your CodeRabbit configuration to a maximum of 15 minutes (900000ms). (1)
  • GitHub Check: Security Audit
🔇 Additional comments (2)
docs/decision-log.md (1)

162-171: Hotfix entry matches the workflow; keep variant lists in sync.

Docs list Generated:, generated at:, Generated by:. The CI regex currently matches those; if “Generated on:” ever existed, add it to both docs and CI to avoid drift.

docs/execution-plan.md (1)

305-311: Narrative aligns with the implemented check.

Entry accurately describes header-scope normalization and the GitHub annotation behavior.

coderabbitai[bot]
coderabbitai bot previously approved these changes Nov 2, 2025
@flyingrobots flyingrobots disabled auto-merge November 2, 2025 00:44
@flyingrobots flyingrobots merged commit fe0ace6 into main Nov 2, 2025
11 of 12 checks passed
@flyingrobots flyingrobots deleted the echo/hotfix-deterministic-rollup-check branch November 2, 2025 00:44
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants