[WIP] DO NOT MERGE: Changelog section scaffold for Chainguard Containers

assets/scss/app.scss

@@ -48,6 +48,7 @@
 @import "components/footer-www-match";
 @import "components/footer-border-fix";
 @import "components/header-logo";
+@import "components/changelog";
 
 /** Import DocSearch */
 @import "@docsearch/css/dist/style.scss";

assets/scss/components/_changelog.scss

@@ -0,0 +1,33 @@
+.changelog-label {
+  display: inline-block;
+  font-size: 0.7rem;
+  font-weight: 700;
+  letter-spacing: 0.06em;
+  text-transform: uppercase;
+  padding: 0.2em 0.65em;
+  border-radius: 4px;
+  margin-top: 1.5rem;
+  margin-bottom: 0;
+  color: #fff;
+
+  &--breaking-change {
+    background-color: #c0392b;
+  }
+
+  &--update {
+    background-color: var(--primary-2);
+    color: var(--primary-3);
+  }
+
+  &--new-feature {
+    background-color: var(--primary-1);
+  }
+
+  &--deprecation {
+    background-color: #e67e22;
+  }
+
+  & + h4 {
+    margin-top: 0.25rem;
+  }
+}

changelog-1pager.md

@@ -0,0 +1,86 @@
+# **Changelog notifications proposal 1 pager**
+
+**Your Name** [Dana Kleinerman](mailto:dana.kleinerman@chainguard.dev)  
+Proposed Mar 23, 2026***\- DRAFT***   
+**Approvers:** \<approver1@\> \[ \], \<approver2@\> \[ \]  
+**Reviewers:**\<reviewer1@\>, \<reviewer2@\>
+
+## Objective/Goals
+
+Provide customers an easy way to stay up-to-date with changes and audit user access to ensure they are using the latest and securest images available. This would include both notifications about changes as well as the ability to query access data. 
+
+More specifically, 
+
+1. Changelist of anything new or updated within Chainguard, as well as actionable next steps  
+   1. Notifications in console  
+   2. Access to a changelog updates in UI and API (to connect to their own systems)  
+2. Ability to audit specific activity within an org (which users in an org are using which features/images to better track usage patterns and also more easily determine who needs to switch to pulling more up-to-date images. Also useful for staying up-to-date with changes in activity and changes in roles )
+
+Note that for this 1 pager, we’ll only focus on \#1 (Chainguard updates) and change usage/access auditing notifications for a later project.
+
+## Problems To Solve
+
+Today customers have difficulty discovering Chainguard updates that they need to be aware of (breaking changes, incidents, newly available images or image versions, changes in SBOMs, etc).
+
+This can lead to poor outcomes where they are using out of date, vulnerable images, or missing privileged role escalations that might be indicative of bad actors. It can also lead to a diminished user experience that could lead to lower engagement, such as missing out on new features that become available. 
+
+## User Scenarios
+
+This is primarily useful for platform admin/engineers who need changelog information and auditing tooling to help them stay informed and ensure their org is up-to-date. 
+
+From the March CAB, customers expressed interest in changelog notifications and audit history:
+
+* API status call for new images. Could be integrated with internal MCP servers that are connected to open API docs and have some level of internal context  
+* Notifications that address “staleness problem” could be really helpful 
+
+## Requirements & Solution
+
+**MVP requirements for Chainguard changelog notifications**  
+Types of changes to include:
+
+* High priority (no opting out; all admins have this turned on by default)  
+  * Breaking changes  
+  * Incidents  
+  * KEVs  
+  * CVEs   
+  * Any other critical security issues that require immediate action  
+* Medium priority (on by default, but admins can opt out)  
+  * Updates to any image requests the user makes via the image priority request dashboard  
+  * Deprecations  
+  * EOL notifications  
+  * Any changes to roles that are not breaking changes (e.g. adding permissions to existing roles. Would count removing permissions as a breaking change)  
+* Low priority (on by default but easy to opt out. If we see most people opting out due to noise, we can change this to be opt in)  
+  * New images that are available (outside of the ones the user requested)  
+  * Version updates to existing images  
+  * Changes in SBOMs  
+  * New features
+
+Surfaces:
+
+* Console:  
+  * New notifications center to show recent notifications (stored for no longer than a month to reduce noise)  
+    * If users wish to track older notifications, they’ll either need to store them themselves using our API or refer to documentation, which should cover the majority of them  
+  * New settings to modify what notifications the user receives   
+  * Ability to subscribe to notifications with their email address  
+* API/Feed:  
+  * Provide a way to view notifications without going to console or setting up email. Could use an MCP server here.   
+  * (Stretch?) Could we help users automate updates? So that human users don’t need to watch out for every change notification, and allow them to just focus on the critical ones.   
+* Public Documentation  
+  * All breaking changes, updates, new features, deprecations should be included in a version history documentation page that is publicly available.   
+  * Take inspiration from [AWS whats new](https://aws.amazon.com/new/) or [Linear](https://linear.app/changelog). 
+
+## Timeline & Gameplan
+
+| Feature | Surface | Timeline |
+| :---- | :---- | :---- |
+| Public version history docs page | https://edu.chainguard.dev/chainguard/chainguard-images/ | ASAP but can run in parallel with other work |
+| Support for Critical notifications | UI and email | Ideally End of Q1 |
+| Support for Critical notifications | API/Feed  | Q2 |
+| Support for medium priority notifications | All surfaces |  |
+| Support for low priority notifications | All surfaces |  |
+
+## Metrics
+
+* Engagement funnel: Notifications seen \> notifications acted upon \> notifications dismissed/ignored  
+* % interaction via UI versus API 
+

changelog-writeup.md

@@ -0,0 +1,127 @@
+# Chainguard Academy Changelog — Build Summary
+
+## What was built
+
+A new changelog section at `content/chainguard/chainguard-images/changelog/` with the following structure:
+
+```
+changelog/
+  _index.md       — section landing page with links to year pages
+  2026.md         — all 2026 entries
+```
+
+Each year lives in a single file (e.g., `2026.md`). Entries within a year are ordered newest-first, grouped under date headings.
+
+Two supporting files were also added:
+
+- **`layouts/shortcodes/changelog-label.html`** — a shortcode that renders a colored badge for the entry type (e.g., Breaking Change, New Feature, Security Advisory)
+- **`assets/scss/components/_changelog.scss`** — styles for the badges and their spacing relative to entry headings; imported via `app.scss`
+
+---
+
+## Entry format
+
+Each entry in a year file follows this pattern:
+
+```markdown
+## Month Day Year
+
+{{</* changelog-label "Label Type" */>}}
+
+#### Entry title summarizing the change
+
+One or two sentences describing what changed and, if applicable, what the reader needs to do.
+```
+
+Supported label types and their colors:
+
+| Label | Color |
+|---|---|
+| `Breaking Change` | Red |
+| `Update` | Brand aqua |
+| `New Feature` | Brand purple |
+| `Deprecation` | Orange |
+
+---
+
+## Adding real entries
+
+1. **New entry in an existing year** — open the relevant year file (e.g., `2026.md`) and add the entry at the top, under a new or existing date heading. Update the `lastmod` field in the frontmatter to today's date.
+
+2. **New year** — copy `2026.md`, rename it (e.g., `2027.md`), clear the entries, update the frontmatter dates, and add a link to it in `_index.md`.
+
+3. **New label type** — add a CSS rule to `_changelog.scss` following the existing pattern; the shortcode will handle the class name automatically by lowercasing and hyphenating whatever string you pass in.
+
+---
+
+## Connecting to an API
+
+There are two main approaches, and the right choice depends on how fresh the data needs to be:
+
+### Option 1: Build-time fetch (Hugo `resources.GetRemote`)
+
+Hugo can call a remote API at build time and render the response into static pages. You'd replace the hand-authored markdown entries with a Hugo template that fetches JSON from the API and loops over the results, outputting the same label/heading/description structure.
+
+**Pros:** No JavaScript required, pages stay fully static, works with existing layout.
+**Cons:** Data is only as fresh as the last site build. Requires a rebuild (and redeploy) to pick up new changelog entries.
+
+This is the right fit if the changelog is updated infrequently (e.g., a few times a week) and your CI/CD already triggers builds on a schedule or webhook.
+
+### Option 2: Client-side fetch
+
+A small JavaScript snippet on the changelog page fetches from the API at page load and renders entries into the DOM. The markdown file would just be a shell with a placeholder element.
+
+**Pros:** Always up to date without a rebuild.
+**Cons:** Requires JS, adds a loading state, and the Hugo shortcode/label system wouldn't apply — you'd need to replicate the badge styling in JS-rendered HTML.
+
+### Recommendation
+
+Given that this is a Hugo static site and the changelog doesn't need to be real-time, **Option 1 is the cleaner fit**. The year files (`2026.md`) would become templates rather than authored content, and the `changelog-label` shortcode logic would move into the template loop.
+
+When the API is ready, the migration path would be:
+1. Agree on the JSON schema the API returns
+2. Write a Hugo partial that maps API fields (change type, date, title, description) to the existing visual structure
+3. Replace the authored year files with template-driven ones that call `resources.GetRemote`
+
+---
+
+## Proposed API JSON schema
+
+Based on the entry structure used in the static changelog, here is a proposed schema for the API response:
+
+```json
+{
+  "entries": [
+    {
+      "id": "2026-04-01-openssl-cve-xxxxx",
+      "date": "2026-04-01",
+      "change_type": "security-advisory",
+      "title": "OpenSSL CVE-2026-XXXXX patched in all images",
+      "description": "All Chainguard Container images containing OpenSSL have been updated to address CVE-2026-XXXXX, a high-severity vulnerability affecting TLS handshake processing. Pull the latest version of any affected image; if you are pinned to a digest, update your digest reference.",
+      "affects": "All images containing OpenSSL",
+      "action_required": true,
+      "links": [
+        {
+          "label": "Learn more",
+          "url": "https://edu.chainguard.dev/chainguard/chainguard-images/changelog/2026/#openssl-cve-2026-xxxxx-patched-in-all-images"
+        }
+      ]
+    }
+  ]
+}
+```
+
+### Field reference
+
+| Field | Type | Description |
+|---|---|---|
+| `id` | string | Unique identifier; used to generate anchor links |
+| `date` | string (ISO 8601) | Date of the change |
+| `change_type` | string (enum) | One of: `breaking-change`, `update`, `new-feature`, `deprecation` |
+| `title` | string | Short entry title (used as the heading) |
+| `description` | string | One or two sentences describing the change and any required action |
+| `affects` | string | Optional. What products, images, or users are affected |
+| `action_required` | boolean | Whether the reader needs to take action |
+| `links` | array | Optional. Related links (docs pages, CVE records, etc.) |
+
+The `change_type` values are intentionally aligned with the CSS class slugs already used by the `changelog-label` shortcode, so no mapping layer is needed when rendering.

config/postcss.config.js

@@ -15,6 +15,7 @@ module.exports = {
         './content/**/*.md',
       ],
       safelist: [
+        /^changelog-label/,
         'lazyloaded',
         'table',
         'thead',
@@ -37,6 +38,7 @@ module.exports = {
           './node_modules/katex/dist/katex.css',
           './assets/scss/*.scss',
           './assets/scss/common/*.scss',
+          './assets/scss/components/*.scss',
           './node_modules/@docsearch/css/dist/modal.css',
         ]),
       ],

content/chainguard/chainguard-images/changelog/2026.md

@@ -0,0 +1,53 @@
+---
+title: "2026 Changelog"
+linktitle: "2026"
+description: "Notable changes to Chainguard Containers in 2026, including breaking changes, new features, updates, and deprecations."
+type: "article"
+date: 2026-01-01T00:00:00Z
+lastmod: 2026-04-01T00:00:00Z
+draft: false
+images: []
+tags: ["Changelog", "Chainguard Containers"]
+toc: true
+weight: 001
+---
+
+## April 1 2026
+
+{{< changelog-label "Breaking Change" >}}
+
+#### Default container user changed to non-root across all images
+
+All Chainguard Container images now run as a non-root user by default, aligning with Chainguard's security-hardening standards. Review your workloads for root requirements and set `securityContext.runAsUser: 0` (Kubernetes) or `--user root` (Docker) where needed.
+
+---
+
+## March 15 2026
+
+{{< changelog-label "Update" >}}
+
+#### OpenSSL updated to address CVE-2026-XXXXX in all images
+
+All Chainguard Container images containing OpenSSL have been updated to address CVE-2026-XXXXX, a high-severity vulnerability affecting TLS handshake processing. Pull the latest version of any affected image; if you are pinned to a digest, update your digest reference.
+
+{{< changelog-label "Update" >}}
+
+#### Provenance attestations now included by default for all images
+
+All images now ship with signed provenance attestations conforming to SLSA Build Level 2. No action is required; attestations are automatically available via the Chainguard API and `cosign verify-attestation`.
+
+---
+
+## March 1 2026
+
+{{< changelog-label "New Feature" >}}
+
+#### Expanded AI/ML image catalog now available
+
+Hardened images for PyTorch, TensorFlow, JAX, and common AI/ML tooling are now available in the standard Chainguard catalog, all built with zero known CVEs and including SBOMs. See the [AI/ML image catalog](/chainguard/chainguard-images/) for the full list.
+
+{{< changelog-label "Deprecation" >}}
+
+#### Legacy image tag format `YYYYMMDD` deprecated
+
+The date-stamped tag format (e.g., `image:20250315`) is deprecated and will be removed in Q3 2026. Migrate to the supported `:latest` or digest-pinned references before then.

content/chainguard/chainguard-images/changelog/_index.md

@@ -0,0 +1,19 @@
+---
+title: "Chainguard Containers Changelog"
+linktitle: "Changelog"
+description: "A record of notable changes to Chainguard Containers, including breaking changes, new features, security advisories, deprecations, and EOL notices"
+type: "article"
+date: 2026-04-06T00:00:00Z
+lastmod: 2026-04-06T00:00:00Z
+draft: false
+images: []
+weight: 095
+---
+
+This changelog covers notable changes to Chainguard Containers, including breaking changes, new features, security advisories, deprecations, and end-of-life notices.
+
+Individual image version updates are not listed here. For image-level update history, use the [Chainguard Console](https://console.chainguard.dev) or the Chainguard API.
+
+Entries are organized by year:
+
+- [2026](2026/)

layouts/shortcodes/changelog-label.html

@@ -0,0 +1,3 @@
+{{- $label := .Get 0 -}}
+{{- $slug := $label | lower | replaceRE `\s+` "-" -}}
+<span class="changelog-label changelog-label--{{ $slug }}">{{ $label }}</span>