Changelog

Overview

Write standardized changelog entries after completing changes. Focus on WHY not WHAT.

Config Loading

1. •Check if .project-orchestrator/project.yml exists
2. •If yes: use config.services[name].changelog for the correct file path
3. •If no: look for CHANGELOG.md in the service directory or project root

When to Trigger

After completing:

• •Bug fixes
• •New features
• •Refactors affecting behavior
• •API changes
• •Configuration changes

Skip for: typo fixes, comment-only changes, test-only changes

Format

### YYYY-MM-DD - Brief Title

**Summary:** One-line description.

**What prompted the change:**
- Motivation or problem

**Problem solved:**
- What this enables

Location

Write to the affected service's changelog path from config.services[name].changelog.

If no changelog path is configured:

• •Check if {service_path}/CHANGELOG.md exists
• •If not, check if CHANGELOG.md exists at project root
• •If neither exists, ask the user where to write the entry

Multiple services? Write entry to EACH affected service's changelog.

Checklist

• • Date format: YYYY-MM-DD (not "Jan 17")
• • Title: Brief, describes outcome (not implementation)
• • Summary: One line, WHY not WHAT
• • Prompted: What problem existed
• • Solved: What's now possible
• • 10-20 lines max
• • Written to correct service changelog

Red Flags

Example

### 2026-01-17 - Fix SSE reconnection dropping notifications

**Summary:** SSE connections now preserve undelivered notifications during reconnect.

**What prompted the change:**
- Users reported missing notifications after connection drops

**Problem solved:**
- Notifications queue during disconnect and deliver on reconnect