Skip to content

Commit 17ee6dd

Browse files
waldekmastykarzgarrytrinder
waldekmastykarz
authored and
garrytrinder
committed
Add release announcement skill and example template for Dev Proxy
1 parent 6e22ce6 commit 17ee6dd

File tree

2 files changed

+227
-0
lines changed

2 files changed

+227
-0
lines changed

‎.github/skills/dev-proxy-release-announcement/SKILL.md‎

Lines changed: 143 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,143 @@
1+
---
2+
name: dev-proxy-release-announcement
3+
description: This skill should be used when the user asks to "write a Dev Proxy release announcement", "create release notes for Dev Proxy", "write announcement for Dev Proxy version", or needs to convert a Dev Proxy changelog into a marketing-focused release article.
4+
---
5+
6+
# Dev Proxy Release Announcement Writer
7+
8+
Create compelling release announcements for Dev Proxy versions based on changelog input.
9+
10+
## About Dev Proxy
11+
12+
Dev Proxy is an API simulator that helps developers build better apps. Developers use it to emulate APIs and their behaviors, ensuring apps integrate with APIs following market best practices.
13+
14+
## Gathering Changelog Input
15+
16+
STOP - Before writing an announcement, obtain a GitHub release URL.
17+
18+
Request from the user a link to the Dev Proxy GitHub release (draft or published). Then:
19+
20+
1. Fetch the release page to get the list of changes
21+
2. Follow links to related issues and PRs to understand:
22+
- What problem each change solves
23+
- Technical details of the implementation
24+
- User impact and breaking changes
25+
3. Use this context to write the announcement
26+
27+
**For draft releases:** Remind the user to delete the draft after publishing the announcement - otherwise it breaks the build.
28+
29+
## Voice and Tone
30+
31+
Write as a master copywriter and part of the Dev Proxy team. Understand that buying is emotional - use words to tap into readers' emotions.
32+
33+
**Perspective:**
34+
- Write in first-person plural ("We're excited...", "We've improved...")
35+
- Position as team members sharing news, not a changelog dump
36+
37+
**Principles:**
38+
- Skip filler words ("We're pleased to inform you that...", "This release contains...")
39+
- Focus on user benefits, not just features
40+
- Make technical changes relatable and actionable
41+
- Use regular dashes (`-`), never em-dashes (`–` or `—`)
42+
- Use sentence case for titles (only first word and proper nouns capitalized)
43+
44+
**Engagement techniques:**
45+
- Use rhetorical questions ("The upside?", "Why this matters:")
46+
- Add "Why this matters" sections for significant features
47+
- Use emotional hooks ("Future-proof", "with confidence", "no more mysterious failures")
48+
- Keep conversational - explain problems before solutions
49+
50+
## Changelog Analysis
51+
52+
Analyze the changelog to separate functional from non-functional changes:
53+
54+
**Include (functional changes):**
55+
- New features
56+
- Bug fixes affecting user behavior
57+
- Breaking changes
58+
- Performance improvements
59+
60+
**Exclude (non-functional changes):**
61+
- Dependabot updates (codeql-action, checkout, setup-dotnet, etc.)
62+
- Docker workflow updates (metadata-action, setup-qemu-action)
63+
- Internal CI/CD pipeline changes
64+
- GitHub Actions version bumps
65+
66+
## Breaking Changes
67+
68+
For major version releases, lead with breaking changes prominently.
69+
70+
Structure each breaking change with:
71+
- **What changed** - technical description
72+
- **Impact** - how it affects users
73+
74+
Frame bug fixes as improvements: "This was a bug - Dev Proxy wasn't accurately emulating..."
75+
76+
Explain the version bump follows semantic versioning (SemVer).
77+
78+
## Graph API Emulation
79+
80+
When describing Microsoft Graph mocking fixes:
81+
- Emphasize alignment with how Microsoft Graph actually works
82+
- Highlight consistency across environments
83+
- Position fixes as bringing Dev Proxy closer to real Graph behavior
84+
85+
## Announcement Structure
86+
87+
```markdown
88+
# Dev Proxy vX.X.X - [Brief description in sentence case]
89+
90+
**Authors: Waldek Mastykarz, Garry Trinder**
91+
92+
[Opening paragraph - excitement, key highlights]
93+
94+
### **In this version:**
95+
96+
- [Bullet list of main changes]
97+
98+
---
99+
100+
### **[Section title]**
101+
102+
[Description - use "What changed:" and "Impact:" for breaking changes]
103+
104+
---
105+
106+
### **Why upgrade to vX.X.X?**
107+
108+
✅ **Benefit 1** - description
109+
✅ **Benefit 2** - description
110+
111+
### **Try it now**
112+
113+
Download **Dev Proxy vX.X.X** today and build better API-connected applications with confidence!
114+
115+
Got feedback or ideas? [Join us](https://github.com/dotnet/dev-proxy/discussions) and be part of the conversation.
116+
```
117+
118+
## Formatting Rules
119+
120+
- `###` for main headings (bold: `### **Section title**`)
121+
- `####` for subsections within breaking changes
122+
- Regular dashes only
123+
- ✅ for benefit lists
124+
- Bold plugin names: `**PluginName**`
125+
- Code format for commands: `` `devproxy --version` ``
126+
127+
## Output Location
128+
129+
Store in: `Projects/Dev Proxy/Release announcements/vX.X.X.md`
130+
131+
## Workflow
132+
133+
1. Gather changelog (see "Gathering Changelog Input" above)
134+
2. Analyze and categorize changes
135+
3. Identify breaking changes and their impact
136+
4. Draft announcement following the structure
137+
5. Check for duplicate content across sections
138+
6. Verify dashes are regular, not em-dashes
139+
7. Confirm title uses sentence case
140+
141+
## Reference Files
142+
143+
- **`references/example-announcement.md`** - Complete v2.0.0 announcement example

‎.github/skills/dev-proxy-release-announcement/references/example-announcement.md‎

Lines changed: 84 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,84 @@
1+
# Example: Dev Proxy v2.0.0 Release Announcement
2+
3+
This is a complete example of a well-structured Dev Proxy release announcement. Use this as a reference for tone, structure, and formatting.
4+
5+
---
6+
7+
# Dev Proxy v2.0.0 - Enhanced AI telemetry, .NET 10, and breaking changes
8+
9+
**Authors: Waldek Mastykarz, Garry Trinder**
10+
11+
We're excited to announce the release of **Dev Proxy v2.0.0!** Following semantic versioning (SemVer), we're bumping the major version due to **breaking changes** in this release. While these changes are small, they improve Dev Proxy's accuracy and behavior - and we want you to be aware of them.
12+
13+
This release also brings .NET 10 support, enhanced AI telemetry capabilities, and important fixes that make your API simulations more reliable.
14+
15+
### **In this version:**
16+
17+
- **Breaking changes** in date formatting and telemetry behavior
18+
- .NET 10 support
19+
- Enhanced AI telemetry with cached tokens tracking
20+
- Bug fixes and improvements
21+
22+
---
23+
24+
### **Breaking changes**
25+
26+
We've made small but important changes that could affect your existing workflows:
27+
28+
#### **Culture-invariant date formatting in Graph mocks**
29+
30+
Previously, **GraphMockResponsePlugin** formatted dates using your system's culture settings (e.g., `13/11/2025 14:30:00` on French systems vs. `11/13/2025 2:30 PM` on US systems). This was a bug - Dev Proxy wasn't accurately emulating how Microsoft Graph actually works. Graph always returns dates in standardized formats, regardless of where it's running.
31+
32+
**What changed:**
33+
34+
All mocked Graph responses now use consistent, culture-invariant formats that align with how Microsoft Graph actually behaves:
35+
36+
- **HTTP Date headers** use RFC 1123 format: `Sun, 16 Nov 2025 11:16:59 GMT` (per RFC 7231)
37+
- **InnerError.Date properties** use ISO 8601 format: `2025-11-16T11:16:59`
38+
39+
**Impact:** If your tests parse dates from mocked responses, you may need to update them to handle these standardized formats. The upside? Dev Proxy now accurately emulates Microsoft Graph's real behavior, giving you consistent responses across all environments - just like the actual Graph API does.
40+
41+
#### **Smarter telemetry recording behavior**
42+
43+
We've improved how the **OpenAITelemetryPlugin** and **OpenAIUsageDebuggingPlugin** handle their outputs, making them more consistent with other Dev Proxy recording plugins.
44+
45+
**What changed:**
46+
47+
- **OpenAITelemetryPlugin** now only includes requests captured while recording is active in its generated report - aligning with how other recording plugins work
48+
- **OpenAIUsageDebuggingPlugin** now only creates CSV files when Dev Proxy intercepts relevant OpenAI requests
49+
- Running `devproxy --version`, or other non-root commands, no longer creates unnecessary output files
50+
51+
**Impact:** If your automation relies on these files always being created, you'll need to check for their existence before processing them. This change keeps your workspace clean and ensures you only get reports with actual data.
52+
53+
---
54+
55+
### **.NET 10 support**
56+
57+
Future-proof your development workflow with .NET 10. Dev Proxy now runs on the latest .NET runtime, giving you access to the newest performance improvements, security patches, and language features.
58+
59+
Upgrading to .NET 10 ensures Dev Proxy stays aligned with Microsoft's latest development platform, providing you with a faster, more secure, and more capable API simulation tool.
60+
61+
### **Enhanced AI telemetry with cached tokens tracking**
62+
63+
Understanding how your AI-powered applications use tokens is crucial for managing costs and optimizing performance. The **OpenAITelemetryPlugin** now tracks **cached tokens** alongside standard token usage, giving you complete visibility into your OpenAI API consumption.
64+
65+
**Why this matters:**
66+
67+
When your app uses cached prompts, OpenAI charges significantly less for those tokens. Without tracking cached tokens separately, you couldn't accurately measure cost savings or optimize your caching strategy. Now you can see exactly how much you're benefiting from prompt caching, helping you make data-driven decisions about your AI implementation.
68+
69+
---
70+
71+
### **Why upgrade to v2.0.0?**
72+
73+
While the breaking changes are small, they make Dev Proxy more accurate and reliable. **Dev Proxy v2.0.0** ensures:
74+
75+
✅ **Consistent behavior** - Culture-invariant dates work the same everywhere
76+
✅ **Accurate cost tracking** - Complete visibility into cached tokens
77+
✅ **Cleaner workflows** - No more empty telemetry files cluttering your workspace
78+
✅ **Future-ready** - .NET 10 support keeps you on the latest platform
79+
80+
### **Try it now**
81+
82+
Download **Dev Proxy v2.0.0** today and build better API-connected applications with confidence!
83+
84+
Got feedback or ideas? [Join us](https://github.com/dotnet/dev-proxy/discussions) and be part of the conversation.

0 commit comments

Comments
 (0)