---
globs: CHANGELOG.md
alwaysApply: false
---
# Changelog Creation Guidelines

When creating or updating changelogs for the Sentry Go SDK, follow these rules:

## Gathering Changes

Before creating a changelog entry, collect all changes since the last release tag:

### Find the Latest Release Tag
```bash
git tag --sort=-version:refname | grep -E '^v?[0-9]+\.[0-9]+\.[0-9]+$' | head -1
```

### Get Commits Since Last Release
```bash
# Get commit hashes and messages since last tag
git log --oneline $(git describe --tags --abbrev=0)..HEAD

# Get detailed commit information
git log --pretty=format:"%h %s (%an)" $(git describe --tags --abbrev=0)..HEAD
```

### Analyze Changes
For each commit since the last release:
1. Check if it's a merge commit from a PR: `git show --stat <commit_hash>`
2. For PR commits, fetch the PR details to understand the full context
3. Categorize changes as Breaking Changes, Features, Deprecations, Bug Fixes, or Misc
4. Identify any commits that should be excluded (internal refactoring, test-only changes, etc.)

### Example Workflow
```bash
# Check current branch and recent commits
git log --oneline --since="2024-01-01" | head -10

# Get PR information for specific commits
git show <commit_hash> --stat

# Look at file changes to understand scope
git diff --name-only <last_tag>..HEAD
```

Always base changelog entries on the complete set of commits since the last release tag to ensure no changes are missed.

## Version Structure

Use semantic versioning (e.g., `0.34.0`) with this format:

```markdown
## [VERSION]

The Sentry SDK team is happy to announce the immediate availability of Sentry Go SDK v[VERSION].
```

## Section Order

Include sections in this exact order (only include sections that have content):

1. **Breaking Changes** - Changes requiring code modifications
2. **Deprecations** - Features marked for future removal
3. **Features** - New functionality and enhancements  
4. **Bug Fixes** - Fixes for existing functionality
5. **Misc** - Other changes

## Formatting Rules

### Pull Request Links
- Always use format: `([#NUMBER](https://github.com/getsentry/sentry-go/pull/NUMBER))`
- For issues: `([#NUMBER](https://github.com/getsentry/sentry-go/issues/NUMBER))`

### Code Examples
- Use Go syntax highlighting: ````go
- For breaking changes, show both before and after examples
- Include relevant context, not just the changed line

### Descriptions
- Start with action verbs (Add, Fix, Remove, Update, etc.)
- Be specific about what changed
- Include component/module names when relevant
- Keep concise but informative

## Section Guidelines

### Breaking Changes
- Always provide migration examples with **Before:** and **After:** code blocks
- Explain rationale for the change
- Include timeline for removal if deprecating

### Features
- Focus on user-facing functionality
- Include code examples for complex features
- Link to documentation when relevant

### Bug Fixes
- Clearly describe what was fixed
- Include component names (e.g., "Fix race condition in `Scope.GetSpan()` method")
- Reference the specific issue if applicable

### Deprecations
- Include migration guidance
- Specify removal timeline
- Provide alternative solutions

## Content Guidelines

### Include:
- All user-facing changes
- Breaking changes with migration guidance
- New features and enhancements
- Important bug fixes
- Performance improvements
- Security fixes
- Deprecation notices

### Exclude:
- Internal refactoring (unless affects performance)
- Test-only changes
- Documentation-only changes (unless significant)
- Build system changes
- CI/CD changes

## Example Structure

```markdown
## 0.34.1

The Sentry SDK team is happy to announce the immediate availability of Sentry Go SDK v0.34.1.

### Features

- Allow flush to be used multiple times without issues, particularly for the batch logger ([#1051](https://github.com/getsentry/sentry-go/pull/1051))

### Bug Fixes

- Fix race condition in `Scope.GetSpan()` method by adding proper mutex locking ([#1044](https://github.com/getsentry/sentry-go/pull/1044))
- Guard transport on `Close()` to prevent panic when called multiple times ([#1044](https://github.com/getsentry/sentry-go/pull/1044))
```

## Quality Checklist

Before publishing:
- [ ] Version number follows semantic versioning
- [ ] All sections in correct order
- [ ] All PR/issue links working
- [ ] Code examples tested and accurate
- [ ] Breaking changes include migration guidance
- [ ] Descriptions clear and specific
- [ ] Grammar and spelling correct
- [ ] No internal-only changes included

## Notes Section

For significant releases, add a notes section:

```markdown
_NOTE:_
Additional context, warnings, or important information about this release.
```

Use for:
- Go version compatibility changes
- Important upgrade considerations
- Significant behavioral changes
- Performance characteristics
- Known limitations
