phoenix-release-notes

# Release Notes

Create and publish release documentation for Phoenix. This skill walks through a structured
workflow: identify undocumented releases, analyze commits by reading the actual code, draft MDX
files, and update all the documentation touchpoints.

## Tone and Style

Write for a developer who uses Phoenix daily. The voice is technical, friendly, and informative
without being verbose.

- **Active voice, present tense**: "Phoenix now provides..." not "A new feature has been added..."
- **Lead with what the user can do**, not what changed internally. The reader cares about
  capabilities, not implementation details.
- **Concise**: 1-3 sentence intro, then bullet points for details. If a bullet can say it, don't
  write a paragraph.
- **Code examples are mandatory** when a feature has a programmatic API. Show working,
  copy-pasteable snippets. Show both Python and TypeScript when both SDKs are affected.
- **Version requirements in bold**: `**Available in arize-phoenix X.Y.Z+**`
- **No PR numbers, commit hashes, or install commands** in the release notes themselves.

## Packages to Track

| Package | Tag pattern |
|---------|------------|
| arize-phoenix (server) | `arize-phoenix-v*` |
| arize-phoenix-client (Python SDK) | `arize-phoenix-client-v*` |
| arize-phoenix-evals | `arize-phoenix-evals-v*` |
| arize-phoenix-otel | `arize-phoenix-otel-v*` |
| @arizeai/phoenix-client (TS SDK) | Check `js/packages/phoenix-client/package.json` |
| @arizeai/phoenix-cli (TS CLI) | Check `js/packages/phoenix-cli/package.json` |
| @arizeai/phoenix-evals (TS evals) | Check `js/packages/phoenix-evals/package.json` |
| @arizeai/phoenix-mcp (TS MCP) | Check `js/packages/phoenix-mcp/package.json` |
| @arizeai/phoenix-otel (TS OTel) | Check `js/packages/phoenix-otel/package.json` |

## Step 1: Identify Undocumented Releases

Compare GitHub releases against existing documentation to find the gap.

```bash
# Recent GitHub releases
gh release list --repo Arize-ai/phoenix --limit 30

# Existing release note files
ls docs/phoenix/release-notes/*/

# Dates already covered in the aggregate file
grep 'ReleaseUpdate label=' docs/phoenix/release-notes.mdx
```

Each `<ReleaseUpdate>` entry in the aggregate file covers a date. Multiple versions released on the same
date get combined into one entry. Identify releases that have no corresponding coverage.

## Step 2: Analyze Commits

For each undocumented release, examine the actual changes — not just the commit messages.

### Get the changelog

```bash
gh release view <TAG> --repo Arize-ai/phoenix --json body --jq '.body'
```

The release body from release-please lists conventional commits with PR links. Use this as a
starting index, then dig deeper.

### Read the actual code

For each `feat()` and significant `fix()` commit, read the changed files to understand what the
feature actually does. Commit messages are often terse — the code tells the real story. Key places:

- **Server REST endpoints**: `src/phoenix/server/api/routers/v1/`
- **Python client SDK**: `packages/phoenix-client/src/phoenix/client/`
- **TypeScript client SDK**: `js/packages/phoenix-client/src/`
- **UI features**: `js/app/src/pages/`
- **Evaluators**: `packages/phoenix-evals/src/phoenix/evals/`
- **CLI**: `packages/phoenix-client/src/phoenix/client/cli/`
- **Models/providers**: playground and model configuration code

### Classify each change

**INCLUDE** — things users interact with directly:
- New API endpoints or SDK methods
- New UI features or pages
- New model or provider support
- Breaking changes to public APIs
- New CLI commands or flags
- New evaluator types or capabilities
- Performance improvements with visible user impact

**EXCLUDE** — internal housekeeping:
- Dependency bumps (`chore(deps):`, `fix(deps):`)
- Internal refactoring with no API surface change
- Test additions or fixes
- CI/CD and build changes
- Code style or formatting changes
- Internal tooling, repo-internal agent skills (`.agents/skills/`), or dev workflows with no
  product behavior change
- Reverts that cancel out a feature within the same release

If a release contains only excluded changes, skip it — no release note needed.

### Group related commits

Multiple commits often implement a single feature across server + client + UI. A REST endpoint
commit, a Python client wrapper, and a TypeScript client wrapper should become one release note
entry that mentions all relevant package versions — not three separate entries.

## Step 3: Draft MDX Files

### Default to a single consolidated file

**Prefer one release note over many.** Phoenix ships frequently, and a separate page per day
produces a noisy, hard-to-scan release feed. Before creating files, look at the whole batch of
undocumented releases together and ask: can these become **one** multi-topic file (Format B)?

Consolidate into a single file when the batch:

- Spans a short window (roughly a week or a handful of consecutive patch/minor versions), **or**
- Shares a theme (e.g. several time range, metrics, or PXI improvements), **or**
- Individually would produce thin pages (one or two features each).

Each feature inside the consolidated file keeps its own `# Heading`, date line, and
`**Available in arize-phoenix X.Y.Z+**` version line, so per-feature version provenance is
preserved even though they share one page. The frontmatter `title` and file are dated by the
**latest** release in the bundle, and the file `description` summarizes the whole bundle.

Only split into multiple files when a feature is genuinely large enough to deserve a standalone
page (a major launch, a breaking change, or a feature with substantial code examples and its own
media). When in doubt, consolidate — it is easier to read one well-organized page than five thin
ones.

If you are **revising** an existing batch that was already split into several thin files,
consolidate them: create one combined file dated by the latest release, delete the superseded
files (`git rm`), and collapse t