19 · Vendoring instead of a package

Kolofon is not a package you install with a command. An instance pulls its files in, according to a list of paths called the manifest, and builds them locally. This is a solution that every guide files under “do not do this”, so it is worth saying why we do.

Reason one: an instance has to be self-sufficient. The instance repository contains everything needed to build the site, without reaching for a private package registry. If everything on our side disappears tomorrow, the instance still builds and deploys.

Reason two: an instance can read the engine. Not as a minified bundle but as legible source, with comments explaining the decisions. For a tool sold as “your data, your code”, that is not a detail.

The drawback is obvious: updating is an operation rather than bumping a version number. Hence the manifest gained a check mode, which before synchronising verifies that nothing on the engine's side has been modified within the instance. Without it, synchronisation silently overwrites somebody else's changes — and instances are sometimes edited with tools other than ours.

The manifest itself recently received an important fix: it is on its own list, so it synchronises together with the engine. Previously an instance could be left with an old list of paths and quietly miss files added in a newer version. The history of that fix, side effects included, is described in the Changelog series.