Create Changelog Announcement

• Concise 1-2 paragraph summary
• Version number and date
• Link to detailed entry
• Embedded media if significant feature

C. 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 in summary entry

5. Media Handling

When user mentions videos or screenshots:

For YouTube videos (in detailed entry):

<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):

<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
• All three entries created (detailed, summary, sidebar)
• Summary links to detailed entry correctly
• Active voice used where possible
• No em dashes present
• Feature documentation linked if applicable
• Media placeholders added if mentioned
• Writing style guidelines followed
• IDs and file names follow conventions
• All required frontmatter included

8. File Locations Reference

Detailed changelog entries:

• Path: /docs/blog/entries/[feature-slug].mdx
• Example: /docs/blog/entries/chat-sessions-observability.mdx

Summary changelog:

• Path: /docs/blog/main.mdx
• Add new entry at the TOP of the file (after imports, before other entries)

Sidebar announcements:

• Path: /web/oss/src/components/SidebarBanners/data/changelog.json
• JSON array, add new entry at the TOP

Step-by-Step Workflow

Step 1: Gather Information

Ask the user for any missing information:

- What version is this for?
- Do you have a demo video or screenshots?
- What's the primary benefit users will get from this?
- Are there existing docs for this feature I should link to?

Step 2: Search for Related Documentation

# Search for related docs
grep -r "session" docs/docs/observability --include="*.mdx" --include="*.md"

Step 3: Create Detailed Entry

Create /docs/blog/entries/[feature-slug].mdx:

IMPORTANT: Use correct frontmatter format (no authors field):

---