Changelog

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:

---
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.