# Release Notes

# Release Notes

> **Project:** {{PROJECT_NAME}}
> **Version:** {{VERSION}}
> **Date:** {{DATE}}
> **Author:** {{AUTHOR}}
> **Status:** Draft | In Review | Approved
> **Reviewers:** {{REVIEWERS}}

## Document History
| Version | Date | Author | Changes |
|---------|------|--------|---------|
| 0.1     | {{DATE}} | {{AUTHOR}} | Initial draft |

---

## Release Metadata

| Field | Value |
|-------|-------|
| **Version** | {{VERSION}} |
| **Release Date** | {{RELEASE_DATE}} |
| **Environment** | Production |
| **Build** | {{BUILD_ID}} |
| **Git Tag** | `v{{VERSION}}` |
| **Git SHA** | `{{GIT_SHA}}` |
| **Previous Version** | `{{PREV_VERSION}}` |
| **Deployment Type** | {{TYPE}} <!-- Standard / Hotfix / Major / Rollback --> |

---

## Release Summary

<!-- GUIDANCE: 3-5 sentences. Explain what this release delivers and why it matters to users. Avoid technical jargon. -->

{{RELEASE_SUMMARY}}

> Example: "Version {{VERSION}} brings a redesigned checkout experience with 40% fewer steps and improved mobile support. We've also resolved {{N}} user-reported bugs and improved API response times by an average of 30%. This release also includes critical security updates — all users are encouraged to review the Security Updates section."

---

## New Features

<!-- GUIDANCE: Each feature should be understandable to a non-technical audience. Include screenshots if available. -->

### {{FEATURE_1_NAME}}

<!-- GUIDANCE: 2-3 sentences describing what it does and why users will care. -->
{{FEATURE_1_DESCRIPTION}}

**How to access:** {{FEATURE_1_ACCESS}}
**Related ticket:** {{TICKET_1}}

---

### {{FEATURE_2_NAME}}

{{FEATURE_2_DESCRIPTION}}

**How to access:** {{FEATURE_2_ACCESS}}
**Related ticket:** {{TICKET_2}}

<!-- TODO: Add all new features -->

---

## Improvements & Enhancements

<!-- GUIDANCE: Existing features that were made better. Quantify improvements where possible. -->

| Improvement | Description | Impact | Ticket |
|-------------|-------------|--------|--------|
| {{IMPROVEMENT_1}} | {{DESCRIPTION}} | {{IMPACT}} <!-- e.g., "30% faster" / "Reduced errors by 80%" --> | {{TICKET}} |
| {{IMPROVEMENT_2}} | {{DESCRIPTION}} | {{IMPACT}} | {{TICKET}} |
| {{IMPROVEMENT_3}} | {{DESCRIPTION}} | {{IMPACT}} | {{TICKET}} |

---

## Bug Fixes

<!-- GUIDANCE: List all user-facing bugs fixed. Group by area if there are many. -->

| # | Description | Severity | Reported By | Ticket |
|---|-------------|----------|-------------|--------|
| 1 | {{BUG_1}} | {{SEVERITY}} | {{REPORTER}} | {{TICKET}} |
| 2 | {{BUG_2}} | {{SEVERITY}} | {{REPORTER}} | {{TICKET}} |
| 3 | {{BUG_3}} | {{SEVERITY}} | {{REPORTER}} | {{TICKET}} |

<!-- TODO: Add all bug fixes -->

---

## Security Updates

<!-- GUIDANCE: List all security-related changes. Be specific enough for security teams to assess, but not detailed enough to be exploitable. -->

| # | CVE / Reference | Severity | Component | Fix |
|---|----------------|----------|-----------|-----|
| 1 | {{CVE_1}} | {{SEVERITY}} | {{COMPONENT}} | Updated to {{VERSION}} |
| 2 | — | High | Authentication | Fixed timing attack in token comparison |

**Action required by users:** {{USER_ACTION}} <!-- e.g., "None — update applied automatically" / "Users must re-authenticate" -->

---

## Breaking Changes

<!-- GUIDANCE: Breaking changes MUST be documented clearly. Users need to know what to change and by when. -->

{{#if BREAKING_CHANGES}}

> **Warning:** This release contains breaking changes. Review carefully before upgrading.

### Breaking Change 1: {{BC_1_TITLE}}

**What changed:** {{BC_1_WHAT}}
**Why it changed:** {{BC_1_WHY}}
**Who is affected:** {{BC_1_AFFECTED}}
**Required action:** {{BC_1_ACTION}}

#### Migration Guide

```bash
# Before (v{{PREV_VERSION}} and earlier)
{{BC_1_BEFORE}}

# After (v{{VERSION}})
{{BC_1_AFTER}}
```

**Migration deadline:** {{BC_1_DEADLINE}} <!-- When the old behavior will be removed -->

---

### Breaking Change 2: {{BC_2_TITLE}}

<!-- TODO: Add additional breaking changes if applicable -->

{{else}}

**No breaking changes in this release.** All existing integrations and configurations remain compatible.

{{/if}}

---

## Known Issues

<!-- GUIDANCE: Be transparent about known issues. Include workarounds. This builds trust with users. -->

| # | Description | Severity | Workaround | Expected Fix |
|---|-------------|----------|------------|--------------|
| 1 | {{KNOWN_1}} | {{SEVERITY}} | {{WORKAROUND}} | {{FIX_VERSION}} |
| 2 | {{KNOWN_2}} | {{SEVERITY}} | {{WORKAROUND}} | {{FIX_VERSION}} |

---

## API Changes

<!-- GUIDANCE: Any API changes must be documented in detail. Breaking API changes should have a deprecation period. -->

### New Endpoints

| Method | Path | Description |
|--------|------|-------------|
| `{{METHOD}}` | `{{PATH}}` | {{DESCRIPTION}} |

### Modified Endpoints

| Method | Path | Change | Breaking |
|--------|------|--------|---------|
| `{{METHOD}}` | `{{PATH}}` | {{CHANGE}} | Yes / No |

### Deprecated Endpoints

| Method | Path | Replacement | Removal Date |
|--------|------|-------------|--------------|
| `{{METHOD}}` | `{{PATH}}` | `{{NEW_PATH}}` | {{DATE}} |

### Removed Endpoints

<!-- GUIDANCE: Only remove endpoints that were deprecated in a previous release. -->

| Method | Path | Removed in | Replacement |
|--------|------|------------|-------------|
| `{{METHOD}}` | `{{PATH}}` | v{{VERSION}} | `{{REPLACEMENT}}` |

**API documentation:** {{API_DOCS_LINK}}

---

## Database Changes

<!-- GUIDANCE: Document schema changes for DBA review and for downstream consumers. -->

| Change | Type | Table / Collection | Details |
|--------|------|-------------------|---------|
| {{CHANGE_1}} | Add column / Remove / Index / Type change | `{{TABLE}}` | `{{COLUMN}} {{TYPE}}` |
| {{CHANGE_2}} | {{TYPE}} | `{{TABLE}}` | {{DETAILS}} |

**Migration files:**
- Up: `{{MIGRATION_PATH}}`
- Down: `{{MIGRATION_PATH}}`

---

## Configuration Changes

<!-- GUIDANCE: Document any new, changed, or removed configuration keys. -->

| Key | Change | Default | Required | Notes |
|-----|--------|---------|----------|-------|
| `{{KEY_1}}` | New | `{{DEFAULT}}` | Yes / No | {{NOTES}} |
| `{{KEY_2}}` | Changed — `{{OLD}}` → `{{NEW}}` | `{{DEFAULT}}` | Yes / No | {{NOTES}} |
| `{{KEY_3}}` | Removed | — | — | Use `{{REPLACEMENT}}` instead |

---

## Dependencies Updated

<!-- GUIDANCE: List significant dependency updates, especially security-related ones. -->

| Package | From | To | Type | Notes |
|---------|------|-----|------|-------|
| `{{PKG_1}}` | `{{OLD_VER}}` | `{{NEW_VER}}` | Security | CVE-{{ID}} |
| `{{PKG_2}}` | `{{OLD_VER}}` | `{{NEW_VER}}` | Feature | {{NOTES}} |
| `{{PKG_3}}` | `{{OLD_VER}}` | `{{NEW_VER}}` | Maintenance | |

---

## Performance Impact

<!-- GUIDANCE: Quantify any performance improvements or regressions. -->

| Metric | Before | After | Change | Notes |
|--------|--------|-------|--------|-------|
| P95 API latency (overall) | {{BEFORE}}ms | {{AFTER}}ms | {{DELTA}}% | |
| P99 API latency (critical path) | {{BEFORE}}ms | {{AFTER}}ms | {{DELTA}}% | |
| Page load time (FCP) | {{BEFORE}}ms | {{AFTER}}ms | {{DELTA}}% | Homepage |
| Database query time (avg) | {{BEFORE}}ms | {{AFTER}}ms | {{DELTA}}% | |

---

## Contributors

<!-- GUIDANCE: Credit everyone who contributed to this release. -->

| Contributor | GitHub / ID | Contributions |
|-------------|-------------|---------------|
| {{NAME_1}} | @{{GH_1}} | {{CONTRIBUTIONS}} |
| {{NAME_2}} | @{{GH_2}} | {{CONTRIBUTIONS}} |

---

## Related Documents

- [Deployment Checklist](./deployment-checklist.md)
- [Rollback Plan](./rollback-plan.md)

---

## Approval
| Role | Name | Date | Signature |
|------|------|------|-----------|
| Author | | | |
| Reviewer | | | |
| Approver | | | |