docs(sync): add fork sync ledger#97
Merged
Merged
Conversation
|
No actionable comments were generated in the recent review. 🎉 ℹ️ Recent review info⚙️ Run configurationConfiguration used: Organization UI Review profile: ASSERTIVE Plan: Pro Plus Run ID: 📒 Files selected for processing (1)
📝 WalkthroughWalkthroughEstablishes a Fork Sync Ledger system: adds a ledger directory and README, updates policy/config to require in-tree ledger entries, updates workflow docs and the docs index, and adds a concrete ledger entry documenting PR ChangesFork Sync Ledger System
Estimated code review effort🎯 2 (Simple) | ⏱️ ~12 minutes Possibly related issues
Possibly related PRs
Poem
🚥 Pre-merge checks | ✅ 5✅ Passed checks (5 passed)
✏️ Tip: You can configure your own custom pre-merge checks in the settings. Comment |
|
| Filename | Overview |
|---|---|
| .agents/fork-sync-policy.toml | Adds sync_ledger path pointer and in_tree_sync_ledger_required flag with clarifying inline comments; straightforward config extension |
| docs/README.md | Adds a one-line index entry linking to the new fork-sync-ledger directory; consistent with existing style |
| docs/maintainers/fork-sync-ledger/README.md | New directory README defining ledger entry structure; 'should include' list is substantially shorter than the normative list in fork-sync-policy.md, missing ~8 required fields |
| docs/maintainers/fork-sync-ledger/2026-06-03-pr-95-upstream-60c62e3.md | First retroactive ledger entry for PR #95; covers scope, catalog, reconciliation, special handling, and verification; retroactive nature accounts for some gaps vs the new policy requirements |
| docs/maintainers/fork-sync-policy.md | Updates step 11 and the Sync Ledger section to require in-tree ledger entries; adds two new required ledger fields (special-handling highlights, follow-up decisions) |
Flowchart
%%{init: {'theme': 'neutral'}}%%
flowchart TD
A[Start broad upstream sync] --> B[Fetch upstream & origin\nRead policy files]
B --> C[Port changes\nResolve conflicts]
C --> D[Run local gates\nbuild-app, tests, cargo test]
D --> E[Create in-tree ledger entry\ndocs/maintainers/fork-sync-ledger/\nYYYY-MM-DD-pr-NN-upstream-SHORTSHA.md]
E --> F{Entry complete?}
F -->|Missing fields| G[Add: divergence areas, doc review,\nrenamed-path checks, policy gaps,\nbaseline update, classifications,\nuncertainties]
G --> F
F -->|Complete| H[Push & open draft PR\nPR body = concise summary only]
H --> I[Mark ready for review\nCI passes]
I --> J[Merge with merge commit\npreserve upstream identity]
Prompt To Fix All With AI
Fix the following 2 code review issues. Work through them one at a time, proposing concise fixes.
---
### Issue 1 of 2
docs/maintainers/fork-sync-ledger/README.md:14-23
The `should include` list here is substantially shorter than the normative list in `fork-sync-policy.md`'s Sync Ledger section. A contributor or agent who reads this README to guide a new entry would produce one missing: policy files read, every divergence area checked, upstream user-facing doc changes reviewed, readme-relevant additions classified, renamed-path checks completed, policy gaps found or noted, baseline update in Fork Divergences, per-area classification (preserved / upstream implements / obsolete / intentionally changed / uncertain), and unresolved-uncertainty disposition. Adding the missing items here, or pointing to the policy section explicitly, prevents silently incomplete entries.
```suggestion
Each entry should include (see [Fork Sync Policy – Sync Ledger](../fork-sync-policy.md#sync-ledger)
for the complete normative list):
- sync scope: PR, merge commit, base commit, previous baseline, and synced
Linux-port upstream commit;
- upstream refs fetched, policy files read, and every divergence area checked;
- upstream user-facing doc changes reviewed; readme-relevant additions
classified as adapted under local contracts, already covered, intentionally
omitted, or follow-up;
- renamed-path checks completed, including any manual old-path reconciliations;
- policy gaps found and codified, or a note that no reusable gap was found;
- baseline update made in [Fork Divergences](../fork-divergences.md);
- upstream commit catalog grouped by behavior area;
- local reconciliation notes for renamed paths and fork contracts;
- per-area classification: preserved, upstream now implements it, obsolete by
policy, intentionally changed, or uncertain;
- user-facing or maintainer-facing highlights that may need special handling;
- follow-up decision for each special-handling item, including links to existing
issues, newly created issues, or a note that no issue is warranted;
- exact local verification commands and results from local gates and final PR
checks;
- unresolved uncertainties escalated to the operator, or linked to a durable,
discoverable follow-up when escalation is unavailable.
```
### Issue 2 of 2
docs/maintainers/fork-sync-ledger/README.md:8-12
The filename convention `YYYY-MM-DD-pr-NN-upstream-SHORTSHA.md` leaves ambiguous whether the date is the sync date or the entry creation date. The first entry uses today's ledger-creation date (`2026-06-03`) even though PR #95 was merged earlier. Future retroactive entries will face the same question. A one-line note here would pin the convention for all contributors.
```suggestion
Use one file per broad sync, where `YYYY-MM-DD` is the date the sync PR was
merged (use the ledger creation date for retroactive entries):
```text
YYYY-MM-DD-pr-NN-upstream-SHORTSHA.md
```
```
Reviews (2): Last reviewed commit: "docs(sync): clarify ledger policy flags" | Re-trigger Greptile
![greptile-apps[bot]](https://avatars.githubusercontent.com/in/867647?s=60&v=4){kind=small}
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
docs/maintainers/fork-sync-ledger/as the durable in-tree home for broad upstream-sync notesVerification
git diff --cached --checkpassed before commit.git diff --checkpassed before staging.gh issue view 96 --repo nisavid/codex-app-linux --json number,title,body,labels,urlverified the issue body and labels.Related: #96
Summary by CodeRabbit
Documentation
Chores