| 1 |
--- |
| 2 |
globs: CHANGELOG.md |
| 3 |
alwaysApply: false |
| 4 |
--- |
| 5 |
# Changelog Creation Guidelines |
| 6 |
|
| 7 |
When creating or updating changelogs for the Sentry Go SDK, follow these rules: |
| 8 |
|
| 9 |
## Gathering Changes |
| 10 |
|
| 11 |
Before creating a changelog entry, collect all changes since the last release tag: |
| 12 |
|
| 13 |
### Find the Latest Release Tag |
| 14 |
```bash |
| 15 |
git tag --sort=-version:refname | grep -E '^v?[0-9]+\.[0-9]+\.[0-9]+$' | head -1 |
| 16 |
``` |
| 17 |
|
| 18 |
### Get Commits Since Last Release |
| 19 |
```bash |
| 20 |
# Get commit hashes and messages since last tag |
| 21 |
git log --oneline $(git describe --tags --abbrev=0)..HEAD |
| 22 |
|
| 23 |
# Get detailed commit information |
| 24 |
git log --pretty=format:"%h %s (%an)" $(git describe --tags --abbrev=0)..HEAD |
| 25 |
``` |
| 26 |
|
| 27 |
### Analyze Changes |
| 28 |
For each commit since the last release: |
| 29 |
1. Check if it's a merge commit from a PR: `git show --stat <commit_hash>` |
| 30 |
2. For PR commits, fetch the PR details to understand the full context |
| 31 |
3. Categorize changes as Breaking Changes, Features, Deprecations, Bug Fixes, or Misc |
| 32 |
4. Identify any commits that should be excluded (internal refactoring, test-only changes, etc.) |
| 33 |
|
| 34 |
### Example Workflow |
| 35 |
```bash |
| 36 |
# Check current branch and recent commits |
| 37 |
git log --oneline --since="2024-01-01" | head -10 |
| 38 |
|
| 39 |
# Get PR information for specific commits |
| 40 |
git show <commit_hash> --stat |
| 41 |
|
| 42 |
# Look at file changes to understand scope |
| 43 |
git diff --name-only <last_tag>..HEAD |
| 44 |
``` |
| 45 |
|
| 46 |
Always base changelog entries on the complete set of commits since the last release tag to ensure no changes are missed. |
| 47 |
|
| 48 |
## Version Structure |
| 49 |
|
| 50 |
Use semantic versioning (e.g., `0.34.0`) with this format: |
| 51 |
|
| 52 |
```markdown |
| 53 |
## [VERSION] |
| 54 |
|
| 55 |
The Sentry SDK team is happy to announce the immediate availability of Sentry Go SDK v[VERSION]. |
| 56 |
``` |
| 57 |
|
| 58 |
## Section Order |
| 59 |
|
| 60 |
Include sections in this exact order (only include sections that have content): |
| 61 |
|
| 62 |
1. **Breaking Changes** - Changes requiring code modifications |
| 63 |
2. **Deprecations** - Features marked for future removal |
| 64 |
3. **Features** - New functionality and enhancements |
| 65 |
4. **Bug Fixes** - Fixes for existing functionality |
| 66 |
5. **Misc** - Other changes |
| 67 |
|
| 68 |
## Formatting Rules |
| 69 |
|
| 70 |
### Pull Request Links |
| 71 |
- Always use format: `([#NUMBER](https://github.com/getsentry/sentry-go/pull/NUMBER))` |
| 72 |
- For issues: `([#NUMBER](https://github.com/getsentry/sentry-go/issues/NUMBER))` |
| 73 |
|
| 74 |
### Code Examples |
| 75 |
- Use Go syntax highlighting: ````go |
| 76 |
- For breaking changes, show both before and after examples |
| 77 |
- Include relevant context, not just the changed line |
| 78 |
|
| 79 |
### Descriptions |
| 80 |
- Start with action verbs (Add, Fix, Remove, Update, etc.) |
| 81 |
- Be specific about what changed |
| 82 |
- Include component/module names when relevant |
| 83 |
- Keep concise but informative |
| 84 |
|
| 85 |
## Section Guidelines |
| 86 |
|
| 87 |
### Breaking Changes |
| 88 |
- Always provide migration examples with **Before:** and **After:** code blocks |
| 89 |
- Explain rationale for the change |
| 90 |
- Include timeline for removal if deprecating |
| 91 |
|
| 92 |
### Features |
| 93 |
- Focus on user-facing functionality |
| 94 |
- Include code examples for complex features |
| 95 |
- Link to documentation when relevant |
| 96 |
|
| 97 |
### Bug Fixes |
| 98 |
- Clearly describe what was fixed |
| 99 |
- Include component names (e.g., "Fix race condition in `Scope.GetSpan()` method") |
| 100 |
- Reference the specific issue if applicable |
| 101 |
|
| 102 |
### Deprecations |
| 103 |
- Include migration guidance |
| 104 |
- Specify removal timeline |
| 105 |
- Provide alternative solutions |
| 106 |
|
| 107 |
## Content Guidelines |
| 108 |
|
| 109 |
### Include: |
| 110 |
- All user-facing changes |
| 111 |
- Breaking changes with migration guidance |
| 112 |
- New features and enhancements |
| 113 |
- Important bug fixes |
| 114 |
- Performance improvements |
| 115 |
- Security fixes |
| 116 |
- Deprecation notices |
| 117 |
|
| 118 |
### Exclude: |
| 119 |
- Internal refactoring (unless affects performance) |
| 120 |
- Test-only changes |
| 121 |
- Documentation-only changes (unless significant) |
| 122 |
- Build system changes |
| 123 |
- CI/CD changes |
| 124 |
|
| 125 |
## Example Structure |
| 126 |
|
| 127 |
```markdown |
| 128 |
## 0.34.1 |
| 129 |
|
| 130 |
The Sentry SDK team is happy to announce the immediate availability of Sentry Go SDK v0.34.1. |
| 131 |
|
| 132 |
### Features |
| 133 |
|
| 134 |
- Allow flush to be used multiple times without issues, particularly for the batch logger ([#1051](https://github.com/getsentry/sentry-go/pull/1051)) |
| 135 |
|
| 136 |
### Bug Fixes |
| 137 |
|
| 138 |
- Fix race condition in `Scope.GetSpan()` method by adding proper mutex locking ([#1044](https://github.com/getsentry/sentry-go/pull/1044)) |
| 139 |
- Guard transport on `Close()` to prevent panic when called multiple times ([#1044](https://github.com/getsentry/sentry-go/pull/1044)) |
| 140 |
``` |
| 141 |
|
| 142 |
## Quality Checklist |
| 143 |
|
| 144 |
Before publishing: |
| 145 |
- [ ] Version number follows semantic versioning |
| 146 |
- [ ] All sections in correct order |
| 147 |
- [ ] All PR/issue links working |
| 148 |
- [ ] Code examples tested and accurate |
| 149 |
- [ ] Breaking changes include migration guidance |
| 150 |
- [ ] Descriptions clear and specific |
| 151 |
- [ ] Grammar and spelling correct |
| 152 |
- [ ] No internal-only changes included |
| 153 |
|
| 154 |
## Notes Section |
| 155 |
|
| 156 |
For significant releases, add a notes section: |
| 157 |
|
| 158 |
```markdown |
| 159 |
_NOTE:_ |
| 160 |
Additional context, warnings, or important information about this release. |
| 161 |
``` |
| 162 |
|
| 163 |
Use for: |
| 164 |
- Go version compatibility changes |
| 165 |
- Important upgrade considerations |
| 166 |
- Significant behavioral changes |
| 167 |
- Performance characteristics |
| 168 |
- Known limitations |