create-changelog-announcement

# Create Changelog Announcement

This skill guides you through creating complete changelog announcements that include:
1. Changelog entry page in `/docs/blog/entries/` (the changelog index at `/changelog` is generated from these automatically, with pagination)
2. Sidebar announcement card in `/web/oss/src/components/SidebarBanners/data/changelog.json`
3. Roadmap update in `/docs/src/data/roadmap.ts`
4. GitHub discussion closure (if applicable)
5. Social media announcements (LinkedIn, Twitter, Slack)

## Your Core Responsibilities

### 1. **Complete Changelog Creation Workflow**

For every changelog announcement, you create TWO coordinated artifacts:

**A. Changelog Entry** (`docs/blog/entries/[feature-slug].mdx`):
- Comprehensive explanation of the feature or change
- Code examples, screenshots, or embedded videos
- Links to related documentation
- User-focused benefits and use cases
- Two distinct texts: a **short summary** for the `/changelog` index, and the
  **full write-up** for the entry's own page. The short version is the curated
  1-2 paragraph summary (it can differ from the long version's opening; do not
  just copy the first lines of the long write-up). Structure the file as:

  ```mdx
  ---frontmatter---

  import Image from "@theme/IdealImage"; {/* only if you use <Image> */}

  <Summary>

  {/* Optional hero video or screenshot, shown on the index */}

  Curated 1-2 paragraph summary shown on the /changelog index.

  </Summary>

  {/* truncate */}

  {/* Repeat the hero video/screenshot here so it also shows on the page */}

  Full write-up (## sections, videos, code) shown on the entry's page.
  ```

  `<Summary>` renders only on the index list (as the preview, with a "Read
  more" link); it renders nothing on the entry page, so the page shows just the
  full write-up with no duplication. If the feature has a demo video or
  screenshot, put it inside `<Summary>` so it appears on the index, and also in
  the write-up below the marker so it appears on the entry page. Embedded
  videos and images are capped to a centered 680px in CSS, so use the existing
  `<iframe>`/`<Image>` markup as-is.

**B. Sidebar Announcement** (`web/oss/src/components/SidebarBanners/data/changelog.json`):
- One-sentence description
- Link to detailed documentation
- Unique ID with date

### 2. **Information Gathering**

**Before creating any entry, collect:**
- Feature name and description
- Version number (if unclear, ask: "Which version is this changelog entry for?")
- Release date (default to today if not specified)
- Whether user has screenshots/videos (ask if mentioned but not provided)
- Links to related documentation

**Never proceed without** a clear version identifier and feature description.

### 3. **Writing Style Guidelines**

Apply these writing guidelines rigorously:

- **Clarity above all else**: Use 11th grade English for non-technical terms
- **Active voice**: "You can now track conversations" not "Conversations can now be tracked"
- **Short sentences**: Default to punchy sentences; use longer ones only for flow
- **Complete sentences**: Avoid fragments unless brevity clearly improves readability
- **No em dashes (—)**: Use periods, parentheses (), or semicolons ; instead
- **Minimal formatting**: Use bold and bullets sparingly—only when they aid scanning
- **User-focused**: Write "You can now..." not "We've added..."
- **Benefits over features**: Explain what users can do, not what you built

**Examples:**

❌ **Bad**: "We've implemented a new session tracking system that enables users to group related traces—making it easier to analyze conversations."

✅ **Good**: "You can now group related traces into sessions. This helps you analyze complete conversations and track metrics across multiple turns."

### 4. **ID and Naming Conventions**

**Changelog Entry File Naming**:
- Use kebab-case with descriptive names
- Examples: `chat-sessions-observability.mdx`, `pdf-support-in-playground.mdx`
- Keep under 60 characters

**Sidebar Announcement IDs**:
- Format: `changelog-YYYY-MM-DD-feature-slug`
- Example: `changelog-2026-01-09-chat-sessions`
- Must be unique to prevent conflicts

**Version Format**:
- Use semantic versioning: `v0.73.0`
- Include it as the entry's tag (`tags: [v0.73.0]`); the changelog index shows it as a version chip next to the date

### 5. **Media Handling**

**When user mentions videos or screenshots:**

**For YouTube videos** (in detailed entry):
```mdx
<div style={{display: 'flex', justifyContent: 'center', marginTop: "20px", marginBottom: "20px", flexDirection: 'column', alignItems: 'center'}}>
  <iframe
    width="100%"
    height="500"
    src="https://www.youtube.com/embed/VIDEO_ID"
    title="Feature Demo"
    frameBorder="0"
    allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture; web-share"
    allowFullScreen
  ></iframe>
</div>
```

**For images** (in detailed entry):
```mdx
<Image
  img={require('/static/images/changelog/feature-name.png')}
  alt="Feature description"
  style={{display: 'block', margin: '20px auto', textAlign: 'center'}}
/>
```

**Ask for specifics if unclear:**
- "Do you have the YouTube URL for the demo video?"
- "How many screenshots should I add placeholders for?"
- "Where should I place the images in the narrative?"

### 6. **Feature Documentation Integration**

**Always search for related documentation:**
1. Check if a dedicated feature page exists in `/docs/docs/`
2. If found, link to it in both the summary and detailed entries
3. If not found, note this and ask: "Should we create documentation for this feature?"

**Documentation links format:**
- Use relative paths: `/observability/trace-with-python-sdk/track-chat-sessions`
- Not absolute URLs unless external

### 7. **Quality Assurance Checklist**

Before finalizing, verify:
- [ ] Version number present and correct
- [ ] Entry and sidebar announcement created
- [ ] Curated summary wrapped in `<Summary>`, then `{/* truncate */}`, then the