Ted Enjtorian

Posted on May 6

[Release-as-Knowledge-01] The Support Engineer's 30 Minutes

#ai #r2k #pogtask #releaseasknowledge

Why is product release information always so hard to find?

── How Mary's 5 minutes turned into 30, and what it tells us about the implicit knowledge bleeding out of every dev team.

Release-as-Knowledge (R2K) series · Part 1 / 6

At 2:25 PM, Mary gets a Slack message.

"Customer A is upgrading from 2.3.4 to 2.4.1 tomorrow. They're asking what to prepare, how long the downtime will be, and whether any settings need to change. I have a meeting with them in 30 minutes — can you put something together?"

Mary is a support engineer. She has been doing this for three years. She knows exactly what comes next:

Open the GitHub release notes — sketchy, mostly a list of new features
Open Jira — filter for tickets in 2.4, read each description
Open git log — look for commits touching application.yml and migration/
Open Confluence — find the previous 2.3.4 deployment doc
Open Slack and @ three engineers asking "any breaking changes this time?"

Thirty minutes later, she stitches together an answer. She is about 80% sure it's right. The other 20%, she'll handle carefully on the call.

Mary knows every piece of information exists somewhere — the dev team certainly knows what changed, how much changed, and what the risks are. The problem is that this information has no systematic outlet.

Every release, the knowledge inside the dev team's heads ships with the new version. But that knowledge does not travel with the Docker image. It stays in engineers' heads, in PR descriptions, in Slack threads, sometimes in commit messages.

What this article wants to ask: can this be changed? If, when a product is released, "what the dev team knows" was automatically released alongside it — what would the world look like?

This is the opening of a 6-part series. Starting from Mary's pain, we'll walk step by step toward what I believe will become standard ISV practice in the next 3–5 years. Today is about the shape of the problem.

The data the dev team produces — where does it go?

Let's take stock. Every CI/CD pipeline run actually produces a lot:

Version info: semantic version, git commit, git branch, build timestamp, build ID
Test results: unit test pass/fail/skip counts, test report XML, coverage percentage
Static analysis: lint warnings, SpotBugs / SonarQube reports, complexity metrics
Dependency manifest: every Maven / npm / Go module dependency and version (SBOM)
API spec: OpenAPI / gRPC schema, serializable to JSON / YAML
Config schema: Spring Boot spring-configuration-metadata.json, every config key's type and default
DB migrations: Flyway or Liquibase migration scripts, analyzable by tools like Atlas
Build metadata: builder version, base image digest, build args

The list goes on.

But what is the fate of all this data?

70% sits inside the CI system (GitLab CI / Jenkins / GitHub Actions) — wiped after 7 days
20% gets uploaded as a build artifact to some S3 / Nexus — and forgotten
10% gets manually copied into release notes — usually as a summary

There is no automated pipeline that ties this data to the product image and ships it to the people who need it.

The CI/CD designers didn't make a mistake. Their goal was "make the build reproducible," not "let non-developers inside and outside the org query it." From the CI designer's perspective, leaving the data inside CI is correct — from Mary's perspective, it's a disaster.

This is a design blind spot, not a technical bottleneck.

The real pain: knowledge in heads

Worse is the other category of information — the knowledge that genuinely lives inside the dev team's heads:

"What changed in the API this time? Which clients will be affected?"
"There's a DB migration this time — how long does it take? Will it lock the table?"
"Three new settings were added — do customers need to set them? Are there defaults?"
"Which features are still behind unset feature flags?"
"What is the biggest hidden risk this time?"

The answers usually only exist in the PR description and a quick conversation with one or two engineers. Three months after release, even those engineers can't recall clearly.

The fate of this kind of knowledge is even worse:

An engineer leaves and takes it with them
New hires figure it out by trial and error
Customers ask, and we look it up on the spot
Documentation is forever stale
Support starts from zero every single time

What's especially wasteful — the raw material for this knowledge already lives in code and config:

API spec is already structured data (OpenAPI YAML)
Config schema is already structured data (Spring Boot config metadata)
DB migrations are already structured data (SQL files)
Feature flags are already structured data (yaml / database)

It's just that no one turns this raw material into a "human-readable manifest."

Every release, the dev team produces a mountain of structured data, writes a mountain of PR text, leaves a mountain of commit messages. And then, the moment CI finishes, all of it says goodbye to the new version.

A different angle: beyond the binary, what else can a release ship?

Over the past decade-plus, we've put enormous effort into pipelining code:

Git made code versioned and traceable
CI/CD made builds reproducible and auditable
Container registries made delivery versioned and distributable
Helm / Kubernetes made deployment declarative and repeatable

But what about the dev team's knowledge that isn't code?

No git
No CI
No registry
No deployment

That knowledge is stuck in the pre-industrial age.

Which makes me ask: why does "shipping software" only ship the binary?
The binary is for machines to run, but documentation, change descriptions, test results, config diffs — these are for humans to use.

The old design assumption was "code is the core, everything else is peripheral."
But for Mary, the periphery is her job.
For customer DevOps teams, the periphery is what they need.
For sales, the periphery is what they price against.

If we re-imagine: a software release should simultaneously be a "binary release" and a "knowledge release" — what changes?

An intuitive answer: put the data into the image

If the image is the final delivery vehicle, why not put the data inside the image?

Images always get released (otherwise it's not a product)
Images are versioned (the version comes with the release)
Images go through OCI registries (which already have a great query API)
Images are immutable (the contents won't quietly change after release)

The OCI spec already provides several mechanisms — Docker LABEL, image annotations, metadata layers, OCI Referrers. Each one can hold metadata.

But that's just the tooling. The real question is: is any ISV deliberately using these tools to turn the dev team's implicit knowledge into shippable data?

The answer I see: individual tools in the industry are very mature (oasdiff for API diffs, Atlas for DB schema migrations, Confluent Schema Registry for event schemas), but the niche of "integrating it for non-dev audiences" is empty.

Each tool produces its own diff report.
Release notes are still written by engineers manually pulling excerpts from those diffs.
There is no unified mechanism for "auto-generate a customer-facing impact report before upgrade."

That gap — is what the next 5 parts of this series are here to fill.

Giving this direction a name

If we want to turn "a software release is also knowledge transfer" into something practical, adoptable, and declarable, it needs a name.

Just as Infrastructure-as-Code (IaC) made infrastructure into manageable code, I call this direction:

Release-as-Knowledge, or R2K for short.

R2K is not a tool, not a product. It's a thesis:

A software release should simultaneously be a knowledge release.
The implicit knowledge produced by the dev team should become explicit data,
and ship together with the image.

Starting next part, we get into concrete mechanisms. I'll lay them out as R2K Levels (a progressive ladder, in the style of SLSA Levels):

Level 1 · Identify — Docker LABEL + OCI standards, achievable in 1–2 weeks
Level 2 · Trust — /r2k/ snapshots + index.yaml table of contents, 2–3 weeks
Level 3 · Understand — Change Manifest integrating API/DB/Config diffs, 6–8 weeks
Level 4 · Share — OCI Referrers, cross-org knowledge transfer and badges

Each level has standalone value. You don't have to do them all at once.

What's coming in the series

Six parts in total:

Part 1 (this one) — The problem: dev team knowledge bleeding away
Part 2 — Starting from LABEL (R2K Level 1 · Identify)
Part 3 — Two-Tier Metadata Pattern + /r2k/index.yaml (R2K Level 2 · Trust)
Part 4 — Change Manifest: the first cross-tool artifact (R2K Level 3 · Understand · with Mode A/B AB plan)
Part 5 — Mary's next version: what R2K-aware tooling looks like
Part 6 — The R2K Manifesto: the next dimension of software release (8 principles)

Closing

Back to Mary.

Next week she'll get another Slack message like this one. A customer will ask "what do I need to do to upgrade?" again. She'll open five browser windows again, @ three engineers, stitch together an 80%-correct answer.

This is not Mary's problem.
This is not the engineers' problem.
This is a design problem — when we designed CI/CD, we didn't think about non-developers needing this data. When we designed release notes, we treated them as an engineer side-product, not a support team main-product. When we designed the image, we only thought about delivering a binary, not delivering knowledge.

What this series wants to say: this design can change.
The tools are already in place — OCI spec, diff tools, registries — all off-the-shelf.
What's missing isn't technology, it's integrative design — a design we call R2K.

The knowledge in the dev team's heads ships with every new version — but that knowledge does not ship with the image.

That sentence is the starting point of this series.
From Part 2 onward, we get into concrete mechanisms — beginning with the simplest and most underestimated of all: Docker LABEL, and how R2K Level 1 lands in practice.

If your team has a Mary moment too, I'd love to hear your story.

R2K series navigation