Never Hand-Stage a File Somebody Else Is Editing

The Files With No Owner

Most of a landing touches material that belongs to exactly one unit of work, and a claim protects it. But a few files are shared by everyone: a registry that every new item registers in, a message catalog that every new item adds keys to. Nothing claims those, several sessions edit them the same afternoon, and that is where the interesting failures live.

The asymmetry is worth learning, because it tells you which half-finished state is dangerous. A registry entry whose material has not landed yet renders nothing and crashes nothing — it fails safe. A registry entry whose message keys are missing does not crash: the site's translator logs an error and renders the raw key path, on the live page, as the card's own text — it fails in public. So the damaging combination is exactly one: committing a neighbor's registry entry without their message keys.

Which yields a rule sharper than "be careful with shared files": check the key, not the entry. Before committing shared wiring, assert that every entry in the registry — not only yours — resolves in every catalog. If somebody else's does not, wait. Do not helpfully author their block.

The Policy That Beat Every Clever Alternative

When many sessions run in parallel, the settled answer is: each session commits only its own material, and one final pass wires all the shared registration together in a single coherence-checked commit. It has a visible cost — until the wiring lands, the material exists and is not indexed anywhere — and naming that cost out loud is part of proposing the policy.

It also has a property that is easy to miss: leaving both your registry entry and your catalog keys uncommitted in the working tree is safe and self-healing. They travel together, so whichever session commits the shared files next carries yours as a complete unit. The anxiety that makes people reach for clever staging is unfounded; the wiring does not need to be held hostage until the repository is quiet.

What generalizes is this: the rule for a shared file is not "be careful" but knowing which half-finished state fails in public. Leave the ones that fail safe alone and block the single public one with a check. Then what you have to be careful about shrinks to one list, and a list can be turned into a script.

Under concurrent writers, scope by paths and never hand-stage — cleverness at the staging layer is a footgun, not an isolation mechanism. The mechanism that works is the scratch index two lessons back, and it works precisely because it builds the commit without touching shared state at all.

Code

The coherence check, and the failure it prevents·bash

# Run this BEFORE committing shared wiring. Note it checks EVERY
# entry, not just the one you added.

for key in $(extract_i18n_keys_from registry.tsx); do
  for catalog in messages/*.json; do
    # the key PATH must resolve - a grep for the string would also
    # match a translated value that happens to read the same
    jq -e --arg k "$key" 'getpath($k | split(".")) != null' \
      "$catalog" >/dev/null || {
      echo "WAIT: '$key' missing from $catalog"
      echo "      it is not yours. do NOT author their block."
      exit 1
    }
  done
done


# WHY: the three half-states are not equally dangerous.
#
#   registry entry + material not landed
#     -> the renderer maps over entries and skips ones whose
#        material is missing. NO card, NO crash. fails SAFE.
#
#   catalog keys + no registry entry
#     -> unused keys are inert. fails SAFE.
#
#   registry entry + MISSING catalog key
#     -> no crash: the translator logs an error and renders the
#        raw key path as the card's text. fails IN PUBLIC, and
#        it ships under YOUR commit.
#
# So sweeping a neighbor's ENTRY into your commit is benign.
# Sweeping their entry WITHOUT their keys is the one damaging
# combination - hence: check the key, not the entry.

Exercise

Find the files in your repository that every new feature has to touch — a registry, a catalog, a route table, an index. For each, write down the three half-states: entry without content, content without entry, entry without its dependencies. Mark which ones fail safe and which fail loud. The loud one is your coherence check, and it is usually a five-line script nobody has written.

Hint

The check has to cover every entry rather than only the one being added, because the failure you are preventing is shipping somebody else's half-finished work under your commit. A check scoped to your own change passes happily in exactly the situation it exists to catch.

The Files With No Owner

The Policy That Beat Every Clever Alternative

Code

External links

Exercise

Progress

Comments 0