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

Bad	Good
"Updated code"	"Fix bookmark sync failing silently"
"Fixed bug"	"Prevent duplicate records on import"
Lists files changed	Explains behavior change
50+ lines	10-20 lines
Entry in root README	Entry in service CHANGELOG.md

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