Skip to content

emrg: the open-source template says to read the code you touch, never to name what else reads it #2792

Open

Description

@argszero

What is missing

emrg/server/open_source_prompt.md §3.1.5 Implement says to read the surrounding context before editing and to understand the responsibilities of the code being touched. It says a behaviour change carries every document it invalidates (§3.1.5, "The documents a change invalidates move with it") and that a translated twin is edited in the same change.

It says nothing about the code that reads the name a change alters.

So a round can widen a return type, make an argument required, move a function out of its file, or delete an export, having read the file it edited and the documents that describe it, and submit a pull request whose diff is coherent on its own terms while every caller it did not open is now broken.

Where this was observed

A task contributed against a project that keeps its own review checklist for changes to its core and protocol surfaces. That checklist's first question is, in substance: what else still calls the function you changed?

The installation had written that question into its own task configuration because the template did not carry it. The template is where it belongs — a contribution's readers are a general property of changing a name, not a fact about one repository.

Why the existing rules do not cover it

  • §3.1.3 Read before writing covers understanding a project before contributing: its conventions, its design intent, its documents. Reading the file you edit is not the same act as enumerating what reads it.
  • §3.1.5's documents rule is about prose — a README, an install guide, a protocol document. It explicitly scopes itself to documents the change invalidates, and a caller is code.
  • A test suite is not a substitute. A caller that is exercised by no test, or reached only through a path the suite does not drive, stays green while being broken on a real user's route.

What the fix must satisfy

  1. One rule, in §3.1.5 (§3.1.5 already owns what an edit must satisfy) — not a second copy elsewhere in the template.
  2. It states that a change to a name's meaning carries the readers the change does not itself update, and that they are part of the same change rather than a follow-up.
  3. It says to find them by searching the name, and to search the tree the change will land on rather than the checkout alone, because a merge can bring in a caller no local search has seen.
  4. It says what to do with a reader that genuinely belongs to a different contribution: name it in the pull request, do not leave it for the suite to discover.
  5. A guard pins it — a test asserting the rule is present exactly once, under §3.1.5, with a control that reddens on deletion and on relocation, because a rule that drifts into a neighbouring section is read as that section's rule.

Acceptance

  • emrg/server/open_source_prompt.md §3.1.5 carries the rule, stated once.
  • tests/test_prompt_templates.py pins the phrase, its section by position, and its absence-of-duplicate, and answers both ways.
  • The pin reddens when the rule is deleted and when it is moved to another section; it passes on the tree as submitted.
  • tests/ passes on the landing tree.

Activity

  1. argszero commented on Nov 10, 2026

    @argszero
    OwnerAuthor

    Handled by #2793

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions