Self-Contained Is the Point

A Repository That Is Also a Backup

These repositories are private, and they carry a doctrine: each one is a self-contained spine for the work inside it. Wherever a checkout of one exists, the thing builds and runs. No registry account, no lockfile resolution against a service that may or may not exist in five years, no internal package server that has to be stood up before anybody can start.

Vendoring preserves that property exactly. A package destroys it in a specific, easy-to-underrate way: the checkout is no longer the code. It is the code minus its dependencies plus a promise that the dependencies can be fetched. That promise is usually kept. "Usually" is doing real work in that sentence, and for an archive with a horizon measured in years rather than sprints, it is the wrong bet.

The Diff Is a Feature

The second property is one people notice only after they have lived without it. When the shared layer changes, the consumer's history shows the change as code. Open the commit, read the diff, see exactly which lines of the shared client moved.

With a package, the same event appears in the consumer as a single line: a version number went from one value to another. Everything that actually happened lives in a different repository, behind a tag, reachable only if you go looking. For a routine upgrade that indirection is fine. For the moment when you are bisecting a behavior change and the only thing in the consumer's history is a number, it is the difference between five minutes and an afternoon.

Indirection you never traverse is documentation you never read. Every layer of indirection between a change and the place it takes effect is a place where a reader can stop. A version bump is a perfectly good abstraction as long as somebody is willing to walk through it — and the honest question is not whether that is possible but whether, at 2am, it actually happens.

The Precedent This Family Was Already Using

The model was not invented for the kit. The same family already distributes a shared set of instruction files to several machines the same way: a canonical source, a deploy step that copies with a checksum, and a check that detects any copy which has stopped matching. Same three parts, different content.

That mattered at decision time, because it meant the model was not a hypothesis. The failure modes were already known — a machine that was missed, a copy someone edited in place — and the mitigations were already in place. Choosing it for code was extending a working practice by one domain rather than importing a new one.

Code

The self-contained test, and what it is really asking·bash

# The only honest way to check the property: clone into a scratch
# directory with the network off and see whether it stands up.

git clone --no-local ./consumer-repo ./cold-checkout
cd ./cold-checkout

# No install step. No registry. No lockfile resolution.
python -m pytest tests/ -q

# What this proves for a VENDORED consumer: the shared code is in
# the tree, so the suite runs. The drift test skips politely when the
# kit repo is absent, which is exactly right - a cold clone must not
# fail because a SIBLING repository is missing.
#
# What it would prove for a PACKAGED consumer: nothing, because the
# first import fails until a registry is reachable.


# The mirror question, which is the one people forget to ask:
# can the shared repo be rebuilt from a consumer if the kit is lost?
#
#   grep -rl "GENERATED FROM" consumer-repo/
#
# Every vendored file names its source path, so the tree can be
# reassembled by hand. Not a backup strategy - but it is the reason
# the header carries a PATH and not just a commit.

Exercise

Clone one of your repositories into a fresh directory with networking disabled and try to run its test suite. Write down every step that failed and what it needed from the network. Then decide, for each one, whether that dependency is buying you something you actually use — and note which of them would still be resolvable in five years.

Hint

Most projects fail at the first install step, which tells you nothing interesting. The useful list is what fails *after* you allow a local package cache: those are the dependencies on services rather than on code, and they are the ones with the shortest shelf life.

A Repository That Is Also a Backup

The Diff Is a Feature

The Precedent This Family Was Already Using

Code

External links

Exercise

Progress

Comments 0