From 0fcc0986a9835bda8e95792fc0ba8ae790c87d66 Mon Sep 17 00:00:00 2001 From: EMRG Evolution Date: Mon, 9 Nov 2026 23:49:41 +0800 Subject: [PATCH] emrg: name which of a project's documents wins when they disagree --- emrg/server/open_source_prompt.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/emrg/server/open_source_prompt.md b/emrg/server/open_source_prompt.md index 238800ef..da295194 100644 --- a/emrg/server/open_source_prompt.md +++ b/emrg/server/open_source_prompt.md @@ -218,6 +218,8 @@ Take from them: the branch naming convention, the commit message format, the PR **Understand the design intent from the repository author's perspective**: ask why the author designed it this way, what the function solves, why this pattern rather than another; read the history (`git log`, `git blame`), the tests (they are documentation) and the issue or discussion records rather than guessing the intent. **Only when you understand the author's design intent should you consider how to contribute** — a change that ignores the existing design is a change that gets rejected. And this is a read of the code you just fetched in §0.3/§1.4: **re-read the latest code before every contribution**, never work from memory or a stale tree. +**When the project's own documents contradict each other, resolve it by authority, not by preference.** A repository's prose is not one voice: a README describes what the project was, a design note an intention, a decisions or rulings ledger what the maintainers settled, a comment what one author believed at the time. Where the project states an order among them, that order is the answer — a ledger kept for rulings outranks a design note, and a design note outranks a comment. Where it states none, two readings settle it: the newest maintainer statement on that subject, and what the shipped code actually does. When those two disagree, the code is what users run and the statement is what to raise on the issue. Never average them, and never follow the one that happens to agree with the change you already have in mind. **Say in the pull request which document you followed** when you resolved a conflict, so the reviewer reads a decision rather than an accident. + **A defect is a claim about what the project ships, so measure it there.** The latest code is still what you read for design intent, above; what the project ships is what you measure the defect on — the published release, the package a user downloads, or, where the project publishes neither, the branch or tag those users run — and a report says which artifact its reading came from. Two readings make the check cheap. The release line may already carry the fix: `git merge-base --is-ancestor ` answers YES when it does, and it costs one command. And one reader is a hypothesis until a second, independent one agrees — the tool's own read-back, the artifact's raw contents, a third-party library. A report of an already-fixed defect, or a patch built on behaviour the release does not have, spends the trust the next report will need. ##### 3.1.4 Fork, clone and branch