The OCI runtime spec says a bundle may need adjusting on a new host, and its docs build runs a pandoc pinned to 2020

A bundle copied to another host may need configuration adjusted

The use cases section is written for three different readers, and the first one contains the sentence that matters most.

An application bundle builder produces a directory holding everything needed to launch an application as a container. That directory contains the configuration file, and the file splits what goes into it into two categories.

Host-independent details are things like which executable to launch. Host-specific settings are things like mount locations, hook paths, Linux namespaces and cgroups.

Then the consequence: because the configuration includes host-specific settings, bundle directories copied between two hosts may require configuration adjustments.

That is the single most consequential sentence in this README for anyone treating an OCI bundle as a portable artefact. The bundle is a directory of files that are portable; the configuration inside it is not, because paths to mounts and to hook binaries are paths on the machine that built it.

It also tells you where the portability boundary sits. The content you ship is portable by construction. The wiring you ship is portable only if you generate it on the target, or parameterise it.

This is stated in the use cases rather than in the normative text, which is worth noting: it reads as guidance for the reader rather than as a requirement on the format.

Typos go straight to a pull request, design changes need an email first

The contributing section contains a process rule that is unusual in a specification repository, and it is stated as a rule.

The project welcomes submissions but asks you to let everyone know what you are working on. Before a nontrivial change to the specification, you are asked to send mail to the mailing list to discuss what you plan to do.

Four reasons are given. Everyone gets a chance to validate the design. It prevents duplicated effort. It ensures the idea fits. And then the one that makes it a rule rather than a preference: it guarantees the design is sound before code is written, and a pull request is not the place for high-level discussions.

Then the exception, in the next line: typos and grammatical errors can go straight to a pull request.

That exception is doing real work. It is what makes the rule workable, because prose fixes do not need consensus and specifications accumulate typos. The repository even ships a spell checker configuration, which is consistent with treating written prose as reviewable at speed and designed material as reviewable by discussion.

The split also tells you what this project considers expensive. Changing what a runtime must do is expensive and goes through a list. Changing what a sentence says is not.

Sign-off requires your real name and no pseudonyms

The commit requirements are two subsections, and the first one has an unusual clause.

The sign-off is described as a simple line at the end of a patch's explanation certifying that you wrote it or otherwise have the right to pass it on. The rules are quoted from a well-known certificate text, and the block the README reproduces opens like this:

Developer Certificate of Origin
Version 1.1

Copyright (C) 2004, 2006 The Linux Foundation and its contributors.
660 York Street, Suite 102,
San Francisco, CA 94110 USA

That block is truncated partway through the second option, ending mid-sentence where the contribution is described as being based upon previous work.

The requirement is then spelled out concretely: add a line to every commit message containing your name and email.

And then this:

using your real name (sorry, no pseudonyms or anonymous contributions.)

That is a stronger position than most projects take. A certificate of origin exists to establish provenance, and most projects accept a pseudonym as provenance. This one requires the legal name, and says so with an apology in the same sentence.

It is consistent with the rest of the file. There is a mail mapping file at the root of the repository, which is what makes a contributor's identity stable across email changes, and a separate file listing maintainers who have retired. Both exist because the project treats contributor identity as something it tracks deliberately rather than incidentally.

The commit style rules that follow are the conventional eight, including a fifty character subject limit, imperative mood, and one keyword to scope the change.

The version document is generated from a Go package

The repository's language is recorded as Go, and almost nothing in it is Go. The explanation is one Makefile rule.

The version document is not written by hand. There is a rule declaring that it depends on a file inside a Go package directory, and a second line that runs a small program from a tooling directory and redirects the output into it.

So the human-readable version page in the rendered documentation is a build artefact, and the Go file is the source of truth. That is why this repository, which is a Markdown specification, is classified as a Go project.

The Makefile also derives a host language version by shelling out to the interpreter and cutting the output twice, once to take the third field and once to strip the leading characters. That is what the file uses to decide whether the host toolchain is new enough.

There is a second Go directory, a schema directory, and a pinned commit hash defined as a test fixture. So the code in this repository is not an implementation; it is the generator for one page of the document and whatever keeps the schema consistent with it.

For a contributor this matters practically: if you change the version, you do not edit the Markdown, and a pull request that edits the generated page will conflict with the next build.

Six platform documents exist and the build renders three

The repository holds configuration documents for six platforms plus a generic one.

The generic configuration document is the base. Then there is one each for Linux, FreeBSD, Solaris, Windows, z/OS and virtual machines.

The list of files the documentation build consumes does not match. The build takes twelve files in a fixed order, and among the configuration documents it includes the generic one, the Linux one and the Solaris one. The other three platform documents are in the repository and are not in the rendered output.

The Makefile says why the order matters: it determines how the pages appear in the generated PDF and HTML. So the omission is not accidental shuffling; those three documents are simply not part of the published document.

The same pattern shows up in the tree. There is a runtime document and a Linux-specific runtime document, and a features document and a Linux-specific features document, so the convention throughout is a generic file with platform files beside it.

For an implementer, the practical effect is that the platform you care about may be documented in a file that is not in the published document set, which is a reason to read the repository rather than the rendered specification.

The documentation build runs a pandoc from 2020 and refuses to guess

The build system is a good example of a repository that pins everything it can and fails loudly when it cannot.

Two tools are looked up on the host: a container runtime and a document converter. Both are discovered by asking the shell whether the command exists. If no converter is present but a container runtime is, the build falls back to running a converter inside a container image.

That image is pinned twice: by a full version tag and by a content digest, on a Fedora base. The version in the tag is a converter release from around 2020.

The practical consequence is that the Docker path and the local path can produce different output from different converter versions, and nothing in the build warns about it. If you install a current converter on your machine you will get a different document from the one the container produces, and both will be correct.

The fallback itself is careful. It mounts the repository read-only, mounts the output directory separately, disables an SELinux label so the bind mounts work, and runs as the calling user's numeric identifier so the output is not owned by root.

And when neither tool is available, the build does not degrade. It stops with an error saying it cannot build the target without one or the other.

Four maintainership files and a retired maintainers list

The root listing is mostly documentation, and the governance files are the part worth reading for what they reveal.

There is a governance document, a maintainers file, an owners file for the repository's code, and a file for maintainers who have left. Four files, three of them about who is in charge and one about who used to be.

The retired maintainers file is the unusual one. Publishing a list of people who used to hold the role is a small act of transparency that most projects skip, and it is the sort of thing that tells you a project has been around long enough to have turnover rather than having been assembled all at once.

Two naming inconsistencies sit among them. The maintainers file and the change log have no extension, while the releases document next to them has one, and the release notes are documented in a separate document with its own name.

There is also a spell checker configuration, which is more than most specification repositories have, and it is consistent with the contribution rule that treats prose fixes as something anyone can send.

What is not at the root is a test suite in the usual sense. The one pinned commit hash defined in the build file is a fixture for validating the document toolchain, not a set of behaviour tests, which is what you would expect from a repository whose output is a document.

The charter lives in another repository and two link targets are for other venues

The list of link definitions at the bottom of the README is eight entries long, and reading them tells you something about how old the file is.

The charter points into a different repository entirely, on a branch named master, in a repository whose name is an abbreviation rather than the project name.

The minutes link points at a chat-bot host under the Linux Foundation domain, which is where meeting minutes were archived when they were transcribed from a chat room rather than written.

And one entry points at a conference site under a name that describes a specific event series rather than the project.

None of those three is referenced by the README's own prose. The meetings section tells you to look at the organisation repository for current schedules and says you can find links to agendas and minutes for all prior meetings, which points you elsewhere. So the bottom of the file carries links the text no longer uses.

Two more are unused: a wiki link and a link to an internet calendar specification, both defined and never cited in the visible text.

That is normal drift in a README that has been amended for years. It is also why the charter, which is the document that defines who decides, is one link away in a repository you have to know the name of.

Editorial conclusion

This specification is the right thing to read if you are building a runtime, a hook or a bundle builder, because it is written from three different readers' perspectives and it tells you what a bundle can and cannot carry. Two things to know before you rely on it. It draws a hard line between host-independent and host-specific settings, so a bundle is not portable between machines without adjustment. And it is a document with a governance process, not a library: changes go through a mailing list first, so expect that conversation rather than a quick pull request.

Frequently asked questions

Official sources

1. License: Apache-2.0
2. opencontainers/runtime-spec on GitHub
3. Project website
4. README
5. Releases