Release Notes Data
Relevant source files
The following files were used as context for generating this wiki page:The Docker documentation project utilizes a data-driven approach for managing and publishing release notes and other versioned content. Instead of hardcoding release information directly into pages, the system relies on structured data files, primarily YAML, to define release details. This data is then consumed by various templates and scripts to generate consistent outputs like RSS feeds, documentation pages, and even synchronize with external platforms like GitHub Releases.
This methodology separates content from presentation, allowing for automation and ensuring that information is consistent across different parts of the documentation site and associated services. The repository contains distinct processes for handling release notes for different products, such as Docker Desktop and Moby Engine.
Docker Desktop Release Data
For Docker Desktop, release notes are managed through a central YAML data file. This file acts as a single source of truth for all release versions, which is then used by the Hugo static site generator to build outputs.
Data Structure
The structure of the Docker Desktop release data can be inferred from the RSS feed template that consumes it. The data is stored in a YAML file, likely data/desktop_release.yaml, and contains a list of release objects.
The following diagram illustrates the entity relationship for the release data.
The fields for each release are detailed in the table below.
| Field | Type | Description |
|---|---|---|
version | string | The version number of the Docker Desktop release (e.g., "4.8.2"). |
date | datetime | The publication date of the release. |
summary | string | A brief, one-sentence summary of the release. |
highlights | string[] | A list of bullet points detailing key changes, features, or bug fixes. |
| Sources: layouts/desktop-release/rss.xml:26-30 |
RSS Feed Generation
A primary use of the Docker Desktop release data is to generate an RSS feed, allowing users to subscribe to release announcements. The Hugo template at layouts/desktop-release/rss.xml is responsible for this process.
The template iterates through the first 20 releases defined in .Site.Data.desktop_release.releases and constructs an <item> for each one in the XML feed.
The following diagram shows the data flow for RSS generation.
The core logic for this iteration is shown in the snippet below.
{{- $releases := .Site.Data.desktop_release.releases -}}
{{- range $index, $release := $releases -}}
{{- if lt $index 20 -}}
<item>
<title>Docker Desktop {{ $release.version }} Released</title>
<link>{{ $.Permalink }}#{{ $release.version }}</link>
<pubDate>{{ dateFormat "Mon, 02 Jan 2006 15:04:05 -0700" $release.date | safeHTML }}</pubDate>
<guid>docker-desktop-{{ $release.version }}</guid>
<description>{{ printf "<p><strong>%s</strong></p>" $release.summary | html }}{{ if $release.highlights }}<ul>{{ range $release.highlights }}<li>{{ . | html }}</li>{{ end }}</ul>{{ end }}<p><a href="{{ $.Permalink }}#{{ $release.version }}">View full release notes</a></p></description>
</item>
{{- end -}}
{{- end -}}
Sources: layouts/desktop-release/rss.xml:23-33
Moby Engine Release Note Synchronization
A different process is used for Moby (moby/moby) engine release notes. A shell script, hack/moby-sync-release.sh, automates the synchronization of release notes from the documentation repository to the corresponding GitHub Release on the moby/moby repository.
Synchronization Workflow
The script performs the following steps:
- Accepts a version number as an argument.
- Locates the release notes for that version within a markdown file in
content/manuals/engine/release-notes/. - Extracts the relevant section for the specified version.
- Uses the
ghCLI to query the GitHub API for an existing release matching the version. - If a release exists, it compares the local notes with the notes on the GitHub release (
.body). - If they differ, it outputs the
gh apicommand required to patch the GitHub release with the updated notes. - If no release exists, it outputs the
gh release createcommand to create a new draft release.
This workflow is illustrated below.
Sources: hack/moby-sync-release.sh
Key commands from the script demonstrate this logic.
Extracting notes from Markdown:
grep -A 10000 "## ${version}" "content/manuals/engine/release-notes/${major_version}.md" | \
grep -m 2 -A 0 -B 10000 '^## ' | \
sed '$d'
Sources: hack/moby-sync-release.sh:15-18
Updating an existing GitHub Release:
echo gh api "repos/moby/moby/releases/$release_id" -X PATCH -f '"body=$(cat "'$docs_notes'")"'
Sources: hack/moby-sync-release.sh:39-40
General Data-Driven Content
The use of YAML data files to generate documentation is a recurring pattern in the repository, not limited to release notes. CLI command references are also generated from YAML files located in the data/ directory.
This pattern is confirmed in several places:
- The
agent.ymlfile notes that some content is "generated from YAML in data/ directory". content/reference/cli/docker/README.mdexplicitly states that CLI reference pages are generated by parsing YAML files from_data/engine-cli.- Templates like
layouts/_default/scout-cli.htmlshow how data is loaded fromsite.Dataand rendered into HTML tables and descriptions.
This architecture ensures that structured data, which is often generated from source code or maintained separately, can be easily integrated into the documentation site.
Summary
The docker-docs repository employs a sophisticated, data-centric strategy for managing release notes and other structured content. For Docker Desktop, a central YAML file serves as the source of truth for generating RSS feeds. For Moby, a script automates the synchronization between markdown documentation and GitHub Releases. This data-driven pattern extends to other areas like CLI reference documentation, demonstrating a robust and scalable architecture for maintaining a large and complex technical documentation site.