--- 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 ` 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 --stat # Look at file changes to understand scope git diff --name-only ..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