changelog

---
name: changelog
description: "Blog post authoring for Atmos: MDX template, frontmatter, website/blog/tags.yml and authors.yml rules, problem-first framing, backtick-opening ban, optional cast embeds, and no-Go-internals leakage. Invoke when writing, editing, or reviewing a website/blog/*.mdx changelog post."
metadata:
  copyright: Copyright Cloud Posse, LLC 2026
  version: "1.0.0"
---

# Changelog (Blog Post) Authoring

Use this skill whenever you create or edit a post under `website/blog/`. It is the single source of truth
for the template, tags, authors, and style rules — `CLAUDE.md`, the `pull-request` skill, and the `docs`
skill all point here instead of restating these rules. Don't re-duplicate them elsewhere.

## When a post is required

Only non-draft PRs targeting `main`, labeled `minor` or `major`, need one — see the `pull-request` skill's
label decision tree. CI enforces this via `.github/workflows/changelog-check.yml`, which checks for a new
`website/blog/*.md` or `*.mdx` file (draft PRs, and PRs targeting a branch other than `main`, are exempt
entirely). Write posts as `.mdx` regardless — Rule 3 below embeds `<CastEmbed>` as real JSX, which only
`.mdx` renders; CI accepts `.md` but that's not this repo's convention.
If a change is genuinely internal-only with zero user-visible effect, it doesn't get a post at all — that
invariant belongs to the `roadmap` skill ("no changelog post for internal-only refactors"); don't work around
it by writing an implementation-heavy post instead.

## File and frontmatter

Create `website/blog/YYYY-MM-DD-<slug>.mdx`:

```markdown
---
slug: descriptive-slug
title: "Clear Title"
authors: [username]
tags: [feature]
---
Open on the PAIN the reader already feels — the broken/tedious/confusing thing they live with
today — then name the change as the relief.
<!--truncate-->
## The Problem
...
## The Fix
...
## How to Use It
...
## Get Involved
```

- `.mdx`, YAML frontmatter, `<!--truncate-->` immediately after the intro paragraph(s) — that's what shows in
  the blog feed.
- Never open the body with `## What Changed` — lead with the problem (see Rule 1).

## Tags — read `website/blog/tags.yml`, never invent one

User-facing: `feature`, `enhancement`, `bugfix`, `dx`, `breaking-change`, `security`, `documentation`,
`deprecation`, `experimental`, `atmos-pro`. Internal/contributor-only, zero user impact: `core`.

## Authors — read `website/blog/authors.yml`

Use the individual human contributor's GitHub username, not a generic team byline. This repo's own history
favors real usernames overwhelmingly (e.g. `osterman` and `aknysh` account for the large majority of posts) —
a generic `atmos` author appears on only a small minority of posts and is a pattern to avoid going forward.
**If the contributor isn't in `authors.yml` yet, add them in the same PR** before referencing their username
in frontmatter.

## Rule 1 — Problem-first framing (not feature-first)

The intro (the text above `<!--truncate-->`) must open on the reader's pain, not on what Atmos now does.
Don't make the post self-referential ("Atmos doesn't support X, so we added it") — describe the general
problem or technique first, the way someone outside the project would recognize it, then bring in the fix.

- **Violation** — `2026-07-02-atmos-builds-atmos.mdx` opens: "Atmos now builds itself through a first-class
  Atmos command:" — self-referential and feature-first.
- **Violation** — `2026-06-28-list-dependencies.mdx` opens: "The new `atmos list dependencies` command
  renders..." — feature-first (and also a Rule 2 violation, see below).
- **Correct** — `2026-06-29-ci-log-groups.mdx` opens: "A workflow fails in CI. You open the run and you're
  staring at two thousand lines of undifferentiated output..." — pain first, product named later.
- **Correct** — `2026-07-09-vendor-diff-and-update.mdx` opens: "Bumping a vendored component to a newer
  version has always meant guessing."
- **Correct pattern for a hypothetical vendoring feature**, illustrating the same principle: don't write
  "Atmos doesn't support vendoring, so we added it." Instead: "Projects depend on lots of external artifacts.
  Vendoring is a common technique to bring those into the repo so changes to dependencies aren't opaque. It's
  also supportive of immutable infrastructure." — name the general problem/technique, then the fix.

Structure the body `## The Problem` / `## The Fix` / `## How to Use It` / `## Get Involved`.

### Rule 1a — Open on the real reason, at the scope it actually applies to

Find the actual motivating reason for the change (PR description, linked issue, commit messages) before
writing the intro, and open on *that* — not a plausible-sounding scenario constructed to fit it, and not
narrowed to the one path you happened to notice it through when the real gap is broader. Both are the same
mistake: substituting a specific, contrived framing for the real, general one.

- **Correct** — `2026-07-13-atmos-stack-schema-command.mdx`: "Editors, CI pipelines, and offline
  environments that want to validate stack manifests locally have had one option: fetch the JSON Schema
  from `atmos.tools`... and hope it matches." A real, checkable limitation, not an anecdote.
- **Violation (invented)** — `2026-08-06-toolchain-lockfile-default.mdx` opened with a fabricated "a
  teammate's laptop and CI don't quite match" vignette, when the real reason (stated correctly two
  paragraphs later) was simpler: the fix already existed but was undocumented, so nobody enabled it.
- **Violation (over-narrowed)** — `2026-08-05-taskfile-convergence.mdx` opens "If you've ever tried to move
  a `Taskfile.yml` over to Atmos, you've hit the gap..." — framing a general task-runner deficiency (no
  dependency ordering, no incremental builds — table-stakes features nearly every task runner has) as if it
  only matters to people migrating from one specific competitor. The real problem, stated correctly under
  `## The Problem`, is category-general: Atmos was missing it as a task runner, full stop.

If you can't find the real reason, ask rather than invent one — and state it at the scope it actually
applies to.

## Rule 2 — Never open prose with a backtick

Prose (a sentence, paragraph, or the post intro) must start with a word, not an inline code span or fence.
**Bullets may open with a backtick** — this rule is about prose paragraphs only.

- **Violation** — `2025-10-15-introducing-atmos-auth-list.md:39`: "`atmos auth list` solves these
  challenges..."
- **Violation** — `2026-06-27-git-clone-fork-pr-safety-gate.mdx:9`: "`atmos git clone` is Atmos's native
  replacement for..."
- **Violation** — `2026-06-28-list-dependencies.mdx:18`, `2026-06-04-use-version-ref.mdx:12`: same pattern.
- **Fix pattern**: "The `atmos auth list` command solves these challenges..." — lead with a word, then the
  code span.

## Rule 3 — Cast embedding (optional, preferred when a recording exists)

Only a small minority of recent posts embed a cast — it's a nice-to-have, not a requirement, and should never
block a post. When a recorded demo exists (or is worth recording) under `examples/<name>/` or `demo/casts/...`
per the `atmos-asciicast` skill, embed it near the top of the post, after the intro/truncate:

```mdx
import CastEmbed from '@site/src/components/CastEmbed'

<CastEmbed src="/casts/examples/demo-component-versions/vendor-versions.cast" title="atmos component version vendoring" chrome controls scrubber />
```

- `src` points under `website/static/casts/{examples,demo}/...`.
- Always carry the `chrome controls scrubber` flags.
- **Also set `cast` and `castTitle` in the frontmatter** whenever the post embeds a cast. The changelog
  timeline card (`website/src/components/ChangelogTimeline/TimelineEntry.tsx`) reads only the frontmatter,
  so a post with just a body `<CastEmbed>` shows no player on its card. Use the primary embed's `src` and
  `title`:

  ```yaml
  cast: "/casts/examples/demo-component-versions/vendor-versions.cast"
  castTitle: "atmos component version vendoring"
  ```
- Multiple `<CastEmbed>` tags are fine in one post if there are multiple relevant recordings.
- `CastEmbed` wraps `CastPlayer` and adds Download (rendered GIF/MP4/SVG/WEBM via Atmos Pro) and Share controls,
  on by default against `cloudposse/atmos` at the site build's Git commit (`GITHUB_SHA` in CI,
  `main` for local builds). This lets PR previews download recordings introduced by the same PR.
  Use `gitRef` to override the source revision explicitly; do not hide controls just because a cast is unmerged.
- Follow it with a plain link to the full example when one exists: `[View the full example](/examples/<name>)`.
- Don't use `EmbedExample` in blog posts — that component's README/file-listing duplicates content the post's
  own prose already covers; it's for docs pages that need the "browse the full example" callout instead.

## Rule 4 — No Go / implementation-detail leakage

A blog post is for users, not contributors. Never name Go package paths, internal file layout, or
implementation structure — describe behavior only in CLI/config/output terms.

- **Violation** — `2025-12-18-function-registry-package.mdx`: title itself is "New pkg/function Package for
  Format-Agnostic Function Registry"; body names `pkg/function/`, `pkg/yaml/`, `pkg/aws/identity/`. A business
  reader doesn't care about Go package paths.
- **Correct** — `2026-06-29-ci-log-groups.mdx` and `2026-06-28-list-dependencies.mdx` describe mechanisms only
  in terms of commands, flags, and observable output — never Go internals.

## Rule 5 — Link features to usage documentation

Link the first useful prose mention of a feature, command, flag, configuration field, or YAML
function to the specific usage page or section. A changelog announcement should lead the reader
to instructions they can follow. Keep code blocks copyable and avoid linking every repetition.
Verify the actual route and heading anchor; filenames are not always public URLs. When supported
functionality has no usage documentation, add it to the appropriate reference page before linking.
For retired functionality, link applicable migration or deprecation guidance without rewriting history.

## Pre-publish checklist

- [ ] Intro opens on the problem, not the feature, and doesn't open with a backtick
- [ ] The opening problem is the real, specific reason this change happened (checked against the PR
      description/issue/commits) — not a generic scenario invented to justify it
- [ ] Body follows Problem → Fix → How to Use It → Get Involved (no `## What Changed` opener)
- [ ] Tag(s) exist in `website/blog/tags.yml`
- [ ] Author exists in `website/blog/authors.yml` (added in this PR if new)
- [ ] Feature terms link to verified usage documentation, including relevant section anchors
- [ ] No Go package paths / internal file layout mentioned
- [ ] Cast embedded if a relevant recording exists (optional otherwise)
- [ ] `cd website && npm run build` succeeds

## Related skills

- **`roadmap` skill** — link the post's slug into the shipped milestone (`changelog: 'your-slug'`) once
  published. This skill doesn't own `roadmap.js` edits; hand off to the `roadmap` skill for that.
- **`pull-request` skill** — owns the semver-label decision tree that determines whether a post is required at
  all; this skill only owns the post itself once one is required.