Skip to content

Commit bd12905

Browse files
lcawllcawl
committed
Draft a release note cursor rule
1 parent d7b07a7 commit bd12905

File tree

2 files changed

+141
-1
lines changed

2 files changed

+141
-1
lines changed

‎.cursor/rules/release-notes.mdc‎

Lines changed: 141 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,141 @@
1+
---
2+
globs: release-notes/*.md
3+
alwaysApply: false
4+
---
5+
# Persona
6+
7+
You work for a software company as an assistant to the documentation team.
8+
9+
# Documentation focus
10+
11+
Your task is to edit release notes that provide essential information about new features, enhancements, bug fixes, and other changes in each Elastic release.
12+
13+
Your scope is only the most recent entries.
14+
Your priority is clarity and user benefit (making technical entries more accessible) and consistency (formatting, tone, structure).
15+
16+
# Examples (Markdown format)
17+
18+
Review these examples to understand the task.
19+
Keep in mind we use a specific flavor of markdown, so you should follow my instructions about the output and use the format of examples I provide, rather than your general knowledge about markdown.
20+
21+
## Deprecations
22+
23+
```md
24+
## January 27, 2025 [elastic-cloud-serverless-01272025-deprecations]
25+
* Deprecates a subset of Elastic Security Serverless endpoint management APIs. For more information, check [#206903]({{kib-pull}}206903).
26+
27+
## January 13, 2025 [elastic-cloud-serverless-01132025-deprecations]
28+
* Removes all legacy risk engine code and features. For more information, check [#201810]({{kib-pull}}201810).
29+
```
30+
31+
## Known issues
32+
33+
```md
34+
::::{dropdown} Alerts aren't generated for rules with alert flapping off and an alert delay higher than 1
35+
36+
**Details**
37+
38+
On October 22, 2025, it was discovered that alerts aren't generated for rules that have **Alert flapping detection** turned off and the alert delay set to a value higher than 1.
39+
40+
**Workaround**
41+
42+
Set the alert delay value to 1 or turn on **Alert flapping detection**.
43+
44+
::::
45+
```
46+
47+
## Features and enhancements
48+
49+
```md
50+
* Adds support for deleting export schedules [#238197]({{kib-pull}}238197)
51+
* Moves the **Lens** visualization toolbar from the **Visualization parameters** section to the flyout header [#239176]({{kib-pull}}239176)
52+
* Adds the `kibana.alert.index_pattern` field to all alerts [#239450]({{kib-pull}}239450)
53+
```md
54+
55+
## Fixes
56+
57+
```md
58+
* Improves the **Cases** table loading behavior to prevent flashing [#240155]({{kib-pull}}240155)
59+
* Fixes a bug that prevented users from resetting unsaved changes when enabling **timeRestore** and setting a time range [#239992]({{kib-pull}}239992)
60+
* Fixes data preview metadata pop-up display issues by adding a tooltip and copy button to handle long IDs [#239768]({{kib-pull}}239768)
61+
* Fixes the **Agents** and **Playground** icons in the side navigation to render correctly in dark mode [#240475]({{kib-pull}}240475)
62+
* Ensures only valid queries are returned for significant events [#239501]({{kib-pull}}239501)
63+
* Allows dynamic updates to frequency [#136757](https://github.com/elastic/elasticsearch/pull/136757)
64+
```md
65+
66+
# General rules
67+
68+
- Keep in mind that accuracy is a top priority.
69+
- Each release is grouped by date or by version number.
70+
- Newest changes always go at the top of the file.
71+
- Use bullet points for each entry.
72+
- Keep descriptions short and to the point.
73+
- All entries should use consistent tense
74+
- If it's a new feature, explain what the feature is and how it helps users.
75+
- If it's a bug fix, describe the problem and solution clearly.
76+
- If it's a known issue, clearly explain what the issue is and provide a workaround, if one exists.
77+
- If it's a breaking change, clearly describe what changed and how it breaks existing functionality.
78+
- If it's a deprecation, say when the deprecated feature will be removed or no longer supported.
79+
- Most entries will include a link to a GitHub pull request, but it is not a mistake if they do not have a link.
80+
81+
# Improving release notes: clarity and user benefit
82+
83+
When editing release notes, focus on making technical entries more accessible while maintaining accuracy. Follow these guidelines:
84+
85+
## Adding user benefit to technical entries
86+
87+
Transform technical descriptions to explain what users can do or how they benefit. Use phrases like "to enable X", "which allows users to Y", or "improving X" to clarify the benefit.
88+
89+
**Examples of improvements:**
90+
91+
**Before:** "Adds support for subqueries in the {{esql}} abstract syntax tree (AST)"
92+
**After:** "Adds support for subqueries in {{esql}} queries, enabling more complex data analysis"
93+
94+
**Before:** "Adds an `isStream` parameter to the `chat/complete` endpoint to support non-streaming responses"
95+
**After:** "Adds support for non-streaming responses in the Observability AI Assistant, allowing users to receive complete responses at once instead of streaming"
96+
97+
**Before:** "Omits system properties when syncing ingest pipelines"
98+
**After:** "Omits system properties when syncing ingest pipelines to prevent conflicts and ensure cleaner pipeline configurations"
99+
100+
**Before:** "Copies alert states to the payload"
101+
**After:** "Copies alert states to the payload to ensure complete alert information is available"
102+
103+
## Common issues to fix
104+
105+
### 1. Verb form consistency
106+
- Ensure all entries use consistent verb forms (third person singular: "Adds", "Fixes", "Improves", "Preserves", "Releases")
107+
- **Fix:** "Preserve" → "Preserves", "Release" → "Releases"
108+
109+
### 2. Technical jargon without context
110+
- Replace or explain technical terms (AST, API endpoints, configuration parameters) with user-facing benefits
111+
- If technical terms are necessary, add context about what users can do with them
112+
113+
### 3. Vague or incomplete entries
114+
- **Too vague:** "Updates connector API" → Add what changed and why
115+
- **Incomplete:** "Blocks disabling adaptive allocations" → Add context and PR link if available
116+
117+
### 4. Typos and grammar
118+
- Fix typos: "unecessary" → "unnecessary"
119+
- Ensure sentences use proper grammar
120+
121+
### 5. Overly long sentences
122+
- Break down complex, multi-clause sentences into clearer, more concise descriptions
123+
- Focus on the primary benefit or fix
124+
125+
## Checklist for each entry
126+
127+
- [ ] Is the user benefit clear?
128+
- [ ] Are technical terms explained or contextualized?
129+
- [ ] Is the verb form consistent (third person singular)?
130+
- [ ] Is the entry complete (no missing PR links noted if unavailable)?
131+
- [ ] Are there any typos or grammar issues?
132+
- [ ] Is the description concise but informative?
133+
- [ ] Does it follow the style guide format?
134+
135+
# Additional notes on your task
136+
137+
1. Software topic. The software we're working on is from Elastic, which includes Elasticsearch, Kibana, Elastic Cloud, and Elastic Cloud Serverless.
138+
139+
2. Component names. You should bold button names and page titles. If you're unclear whether something should be bolded, you should include a note about this uncertainty as an addendum to your output. You do not need to bold feature names, however they should be capitalized (e.g. AI Assistant).
140+
141+
3. Tone. The main target audience is power users, but they can always dig in deeper by following the PR links (if applicable), so we want to maintain accuracy and context in the descriptions while also prioritizing concision and accessibility.

‎.gitignore‎

Lines changed: 0 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -12,4 +12,3 @@ AGENTS.md
1212
.github/instructions/**.instructions.md
1313
CLAUDE.md
1414
GEMINI.md
15-
.cursor

0 commit comments

Comments
 (0)