docs: document upstream sync policy and ecosystem-port framing#56
Merged
Conversation
In response to @affaan-m's review on affaan-m/everything-claude-code#1343 (drift concern, request for a documented sync policy and a clear "changed vs copied" delta). - docs/UPSTREAM.md (new): records the upstream baseline SHA (9db98673... — ECC HEAD ~1h before EGC's initial commit), a best-effort sync policy, a category-level changed/copied/removed/ added table, backporting guidance, and a "known drift" section. - docs/.upstream-sync.json (new): machine-readable mirror of the baseline state. A follow-up PR will add a CI validator that asserts these two files agree on the SHA. - README.md: ecosystem-port disclaimer added under the existing attribution. Clarifies EGC does not claim ECC compatibility and links to docs/UPSTREAM.md. - CONTRIBUTING.md: new "Upstream contributions" section explaining when a change belongs upstream too, how to dual-PR, and the procedure for recording a sync. Doc-only. npm run lint and npm test both green (222/222).
![greptile-apps[bot]](https://avatars.githubusercontent.com/in/867647?s=60&v=4){kind=small}
There was a problem hiding this comment.
Your free trial has ended. If you'd like to continue receiving code reviews, you can add a payment method here.
WalkthroughThis PR establishes upstream synchronization policy for EGC as an ecosystem port of ECC. It adds ChangesUpstream Synchronization & Backport Policy
Estimated code review effort🎯 1 (Trivial) | ⏱️ ~5 minutes Suggested labels
🚥 Pre-merge checks | ✅ 5✅ Passed checks (5 passed)
✏️ Tip: You can configure your own custom pre-merge checks in the settings. ✨ Finishing Touches📝 Generate docstrings
🧪 Generate unit tests (beta)
Warning Review ran into problems🔥 ProblemsTimed out fetching pipeline failures after 30000ms Tip 💬 Introducing Slack Agent: The best way for teams to turn conversations into code.Slack Agent is built on CodeRabbit's deep understanding of your code, so your team can collaborate across the entire SDLC without losing context.
Built for teams:
One agent for your entire SDLC. Right inside Slack. 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. Comment |
![cubic-dev-ai[bot]](https://avatars.githubusercontent.com/in/1082092?s=60&v=4){kind=small}
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 1
Caution
Some comments are outside the diff and can’t be posted inline due to platform limitations.
⚠️ Outside diff range comments (1)
CONTRIBUTING.md (1)
127-140:⚠️ Potential issue | 🔴 CriticalFix incorrect tool name mappings.
The
Globmapping is incorrect. According to Gemini CLI documentation,globandlist_directoryare separate tools—globis for pattern-based file discovery, whilelist_directorylists directory contents. ChangeGlob→list_directorytoGlob→glob.Also,
search_file_contentis a legacy alias. The current tool name isgrep_search; consider updating for consistency with the latest Gemini CLI.The other mappings (
read_file,write_file,replace,run_shell_command,google_web_search) are correct.🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the rest with a brief reason, keep changes minimal, and validate. In `@CONTRIBUTING.md` around lines 127 - 140, Update the tool-mapping table so the "Glob" row maps to "glob" (not "list_directory") and replace the legacy "search_file_content" entry with the current "grep_search" name; specifically edit the table entries for the Claude→Gemini mappings (the rows referencing Glob and Grep/search_file_content) to use "glob" and "grep_search" respectively while leaving read_file, write_file, replace, run_shell_command, and google_web_search unchanged.
🤖 Prompt for all review comments with AI agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
Inline comments:
In `@docs/UPSTREAM.md`:
- Around line 117-121: The three consecutive checklist items that start with
"Update" (items referencing updating `lastSyncedSha`/`lastSyncedAt`/`notes`, the
**Upstream baseline** section, and the **Open questions and known drift**
section) are repetitive; rephrase them so each begins differently for
readability—e.g., "Set" or "Modify" for the first, "Align the **Upstream
baseline** section to match" for the second, and "Revise the **Open questions
and known drift** section if any drift items are resolved" for the third—keeping
the meaning identical and preserving item 4 (lint/test) and item 5 (commit
message) as-is; update the bulleted numbered list in the UPSTREAM.md content
(the three list items and their surrounding sentences) accordingly.
---
Outside diff comments:
In `@CONTRIBUTING.md`:
- Around line 127-140: Update the tool-mapping table so the "Glob" row maps to
"glob" (not "list_directory") and replace the legacy "search_file_content" entry
with the current "grep_search" name; specifically edit the table entries for the
Claude→Gemini mappings (the rows referencing Glob and Grep/search_file_content)
to use "glob" and "grep_search" respectively while leaving read_file,
write_file, replace, run_shell_command, and google_web_search unchanged.
🪄 Autofix (Beta)
Fix all unresolved CodeRabbit comments on this PR:
- Push a commit to this branch (recommended)
- Create a new PR with the fixes
ℹ️ Review info
⚙️ Run configuration
Configuration used: Path: .coderabbit.yaml
Review profile: ASSERTIVE
Plan: Pro
Run ID: a4cc4ba7-f926-4c6a-834e-72cc849ca441
📒 Files selected for processing (4)
CONTRIBUTING.mdREADME.mddocs/.upstream-sync.jsondocs/UPSTREAM.md
… translations Response to design feedback on PR #56. Restructure: - docs/UPSTREAM.md -> upstream/README.md - docs/.upstream-sync.json -> upstream/.upstream-sync.json - Co-locates the human doc, the machine state, and the per-language translations under a single dedicated upstream/ folder. The English doc lives at upstream/README.md so GitHub renders it on folder navigation, mirroring the existing docs/ko-KR/README.md convention. Three improvements on the English doc: - Status badges at top (Sync policy, upstream repo, baseline SHA) via Shields.io for at-a-glance signaling. - New "Conflict resolution" subsection under Sync policy: when an upstream change collides with Gemini-native surface area, Gemini CLI native behavior stability takes precedence over upstream alignment. - "Recording a sync" now states the procedure is open to community contributors via PR, not just the maintainer — reduces solo- maintainer bottleneck signal. Translations: - upstream/ko-KR/README.md (Korean) — mirrors English doc 1:1 including badges, conflict resolution, and community language. - upstream/zh-CN/README.md (Simplified Chinese) — same. Cross-references: - Root README.md: disclaimer link retargeted to upstream/README.md. - CONTRIBUTING.md: all docs/UPSTREAM.md and docs/.upstream-sync.json links retargeted to upstream/* paths. - docs/ko-KR/README.md: ecosystem-port disclaimer mirrored under the existing Korean attribution, linking to upstream/ko-KR/README.md. - docs/zh-CN/README.md: previously had NO attribution at all (gap surfaced by planning). Adds the Chinese attribution line plus the ecosystem-port disclaimer, linking to upstream/zh-CN/README.md. Nitpick fix from PR #56 review (CodeRabbit, line 121): "Recording a sync" no longer opens three successive sentences with "Update."; varied to "Update / Bring / If any item is resolved, remove it." Doc-only. npm run lint and npm test both green (222/222).
This was referenced May 12, 2026
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
Response to @affaan-m's review on affaan-m/everything-claude-code#1343. The maintainer flagged drift risk, asked for a documented sync policy, and asked for a clear "changed vs copied" delta. This PR addresses each of those asks in a doc-only change.
docs/UPSTREAM.md(new): records the upstream baseline (ECC9db98673...— the ECC HEAD ~1h before EGC's initial commitff331996), a best-effort sync policy, a category-level changed/copied/removed/added table, and an honest "known drift" section.docs/.upstream-sync.json(new): machine-readable mirror of the same baseline. Sets up the state file that the planned upstream-drift-tracker Action (follow-up PR) will read.README.md: adds an "ecosystem port, not official ECC release" disclaimer right under the existing attribution line, with a link todocs/UPSTREAM.md.CONTRIBUTING.md: adds a new "Upstream contributions (ECC backports)" section between "Submitting a PR" and "Tool Name Conversion". Explains when a change belongs upstream too, how to dual-PR, and how to record a sync.Maintainer asks → file mapping
docs/UPSTREAM.md→ Sync policy sectionREADME.mddisclaimer +docs/UPSTREAM.mdopening paragraphdocs/UPSTREAM.md→ What was copied vs. changed vs. removed vs. added tableSync cadence chosen: best-effort, no committed schedule
Rationale: a solo maintainer cannot reliably commit to a calendar cadence, and a missed promise is itself the kind of drift the policy is meant to prevent. Instead, drift is made mechanically visible by recording the baseline SHA in two places (prose + JSON) and (in a follow-up PR) running a weekly cron Action that opens a tracking issue if the baseline lags upstream HEAD.
Out of scope (deferred)
feat/upstream-drift-tracker). Will readdocs/.upstream-sync.json, compare againstaffaan-m/everything-claude-codeHEAD on a weekly cron, and maintain a single rollingupstream-synctracking issue.UPSTREAM.mdprose anddocs/.upstream-sync.jsonagree. Will land with the action PR (Phase 3 of that plan).docs/zh-CN/README.mdis missing the attribution line that the English and Korean READMEs have.Test plan
npm run lint— cleannpm test— 222/222 (no test changes; doc-only)docs/UPSTREAM.md,docs/UPSTREAM.md→docs/.upstream-sync.json+ ECC repo + baseline commit + initial EGC commit, CONTRIBUTING →docs/UPSTREAM.mdSummary by cubic
Documents the upstream sync policy and clarifies EGC as an ecosystem port, now organized under a dedicated
upstream/folder with a machine-readable baseline, status badges, conflict-resolution guidance, and ko‑KR/zh‑CN translations. UpdatesREADME.md, localized READMEs, andCONTRIBUTING.mdto link toupstream/README.md, add the disclaimer (and missing Chinese attribution), and explain backports, dual‑PRs, and how to record syncs.Written for commit a176681. Summary will update on new commits.
Summary by CodeRabbit