@microsoft/writing-release-notes

---
name: writing-release-notes
description: Generates release notes and changelog entries for the DocumentDB VS Code extension. Use when preparing version releases, creating patch update notes, writing changelog entries, or documenting new features and fixes. Handles both major/minor versions (new file) and patch updates (append to existing file).
---

# Writing Release Notes and Changelog

Generate professional release documentation for the DocumentDB VS Code extension.

## When to Use

- Creating release notes for a new version (X.Y.0)
- Appending patch release notes (X.Y.Z where Z > 0)
- Writing changelog entries for any version
- Documenting new features, improvements, or fixes

## Quick Reference

| Version Type               | Release Notes Action                           | Changelog Action                  |
| -------------------------- | ---------------------------------------------- | --------------------------------- |
| Major/Minor (1.0.0, 1.1.0) | Create new `docs/release-notes/X.Y.md`         | Add new `## X.Y.0` section at top |
| Patch (1.1.1, 1.1.2)       | Append to existing `docs/release-notes/X.Y.md` | Add new `## X.Y.Z` section at top |

## Input Format

You will receive:

1. **Version number** (e.g., `0.7.0`, `0.6.4`)
2. **List of changes** with:
   - Brief description of change
   - Issue link(s) and/or PR link(s)
   - Category: Feature, Fix, Improvement, or Security

## Output Files

### Changelog (`CHANGELOG.md`)

**Location**: `/CHANGELOG.md` (repository root)

**Style**: Concise, technical, factual

For format and examples, see [CHANGELOG-FORMAT.md](./CHANGELOG-FORMAT.md)

### Release Notes (`docs/release-notes/X.Y.md`)

**Location**: `/docs/release-notes/{major}.{minor}.md`

**Style**: Enthusiastic, user-focused, marketing-oriented

For format and examples, see [RELEASE-NOTES-FORMAT.md](./RELEASE-NOTES-FORMAT.md)

## Workflow

### Step 1: Determine Version Type

```
Version X.Y.Z:
├── Z = 0 (major/minor release)
│   ├── Create new release notes file: docs/release-notes/X.Y.md
│   └── Add new changelog section at TOP of CHANGELOG.md
└── Z > 0 (patch release)
    ├── Append patch section to existing docs/release-notes/X.Y.md
    └── Add new changelog section at TOP of CHANGELOG.md
```

### Step 2: Generate Changelog Entry

1. Read [CHANGELOG-FORMAT.md](./CHANGELOG-FORMAT.md) for format
2. Add entry at TOP of `CHANGELOG.md` (below `# Change Log` heading)
3. Keep descriptions brief (1-2 sentences max)
4. Include issue/PR links in format: `[#123](https://github.com/microsoft/vscode-documentdb/issues/123)`

### Step 3: Generate Release Notes

1. Read [RELEASE-NOTES-FORMAT.md](./RELEASE-NOTES-FORMAT.md) for format
2. For X.Y.0: Create new file with full header and "What's New" sections
3. For X.Y.Z: Append patch section to existing X.Y.md file
4. Use exciting language for features, clear language for fixes
5. Include images when applicable (reference existing patterns)

### Step 4: Update Release Notes Index

1. Open `docs/index.md`
2. Find the **Release Notes** section
3. For X.Y.0: Add a new line `- [X.Y](./release-notes/X.Y)` at the top of the list
4. For X.Y.Z (patch): Append `, [X.Y.Z](./release-notes/X.Y#patch-release-vXYZ)` to the existing line for that major.minor version (where `vXYZ` uses no dots, e.g., `v071`)
5. Follow the existing pattern of other entries in the list

## Writing Guidelines

### Changelog Tone

- Technical and factual
- No marketing language
- Focus on WHAT changed

### Release Notes Tone

- Enthusiastic and user-focused
- Highlight benefits to developers
- Use emojis sparingly (⭐ for major features, 💠 for patch items)
- Focus on WHY this helps users

### Link Format

```markdown
<!-- Issue link -->

[#123](https://github.com/microsoft/vscode-documentdb/issues/123)

<!-- PR link -->

[#456](https://github.com/microsoft/vscode-documentdb/pull/456)

<!-- Combined -->

[#123](https://github.com/microsoft/vscode-documentdb/issues/123), [#456](https://github.com/microsoft/vscode-documentdb/pull/456)
```

## Validation Checklist

Before completing:

- [ ] Changelog added at TOP of CHANGELOG.md
- [ ] All issue/PR links are correct and clickable
- [ ] Version numbers match across all files
- [ ] Categories are appropriate (Features, Fixes, Improvements)
- [ ] Release notes use proper header format
- [ ] Patch releases append to existing file with `---` separator
- [ ] `docs/index.md` Release Notes section updated with link to new version