Publication

What a repository has handed over for others to depend on lives in .loom/published/.

Publishing is a change of kind, not a change of status. An unpublished document is an implementation detail you may rename at will. A published one is a contract.

So publication is an act somebody performs — a file moves in — and the move is a diff that shows up in review. A flag in frontmatter is a line nobody notices; this is the moment a thing becomes somebody else’s problem, and it should be unmissable.

ls .loom/published/ is what have we committed to? — and it is the question to ask before changing anything.

Publishing is not an act you can complete alone

A file in .loom/published/ that its intended readers cannot fetch is not published. The move is the act, but the act is not finished until somebody who is not you can perform the read.

The failure is invisible from the inside. Every check available to the publisher passes — the file is there, the commit landed, the path is right. Only a reader can detect it, and a reader who cannot fetch it does not know the document exists to ask about.

The commonest form is a document that answers “why can you not see this?” and is published inside the thing that cannot be seen.

So publication has a visibility, and it is a property of the act rather than of the file. “Others” is not “everyone”. Naming who the readers are is part of publishing, because a repository that depends on this one has to know whether it is inside that set — and because a reader who copies a document out inherits the copy without inheriting the visibility it was published under.

The test is a fetch you did not perform.

Doing it

1. Decide it is a contract and not a detail. This is the whole decision and the rest is mechanics.
2. Move the file into .loom/published/. One commit, so the diff carries it.
3. Say who the readers are — if it is not obvious from where it landed.
4. Fetch it. From somewhere that is not your machine and not your account.
5. Record the decision, if you keep a log.

Step 4 is the one that gets skipped and the only one that can fail. Steps 1 to 3 are things you do; step 4 is a fact about the world that you find out.

Then say what it depends on. A published document that quietly requires a private one has moved the problem rather than solved it.

What is published is a document

Prose, in whatever form its readers need. If a repository organises its thinking some other way internally, that is its own business: a consumer cannot tell whether it did, and must not need to.

What is not exported is not hidden. The rest of the repository is there to read. It is simply not what you depend on.

There is no directory for what is unpublished

Everything else is simply elsewhere in the repository. Naming the complement invents a category — and a directory called internal/ would look like a security boundary and not be one.

This page is a copy of a document published by loom/bedrock, rendered here. The source is https://git.hypertheory-labs.dev/loom/bedrock/raw/branch/main/.loom/published/publication.md and is what the copy is checked against.

What of ours depends on it: .loom/externals/git.hypertheory-labs.dev/loom/bedrock/publication.usages.md