Debian Codegraph @

.cursor/rules/changelog.mdc

raw
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