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**: `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 Individual MDX Files

### File location

```
docs/phoenix/release-notes/{MM-YYYY}/{MM-DD-YYYY}-{slug-title}.mdx
```

Create the month directory if it doesn't exist: `mkdir -p docs/phoenix/release-notes/MM-YYYY`

### Frontmatter title rules (apply to BOTH formats)

Every release note MDX file — single-topic or multi-topic — **must** have a descriptive,
date-prefixed `title` in its frontmatter. The title appears in browser tabs, the sidebar,
and search results, so a generic `"Release Notes"` makes the page indistinguishable from
the index page.

Required format: `title: "MM.DD.YYYY: Descriptive Title"`

- ✅ `title: "04.29.2026: Dataset Upsert"`
- ✅ `title: "05.05.2026: REST API Updates"`
- ✅ `title: "04.30.2026: Annotation Enhancements"`
- ❌ `title: "Release Notes"` — never use this; it collides with the index page
- ❌ `title: "Dataset Upsert"` — missing the date prefix
- ❌ `title: "04.29.2026 Dataset Upsert"` — missing the colon separator

For multi-topic files, the title summarizes the theme of the bundle (e.g.
`"04.30.2026: Annotation Enhancements"`), not any single feature inside it.

### Format A: Single-topic file

Use when one feature is significant enough to warrant its own page.

```mdx
---
title: "MM.DD.YYYY: Feature Title"
description: "One-sentence description of the feature."
---

Introductory paragraph explaining what users can now do.

## Section Heading

- **Bold lead** describing a capability
- **Another point** with technical detail

```python
# Working Python exampl