4 exercises — internal Slack announcements, user-facing feature posts, CHANGELOG format, and external partner notices.
0 / 4 completed
1 / 4
You need to post a release announcement to your engineering Slack channel that your full team can understand. Version 2.4.0 ships a new payment retry logic and a security patch. Which announcement is best?
Option B is a complete internal release announcement with all necessary elements:
Internal release announcement structure: 1. Version + timestamp (UTC) — exact, unambiguous reference point 2. What shipped — per-feature with user impact described, not just technical description 3. Security items — call these out explicitly; include CVE ID and severity; note any active session changes 4. Deployment method — "blue-green, zero downtime" vs. "required restart" affects other teams 5. Affected services — relevant to on-call and integration owners 6. Monitoring links — what dashboards to watch, in #observability 7. Rollback procedure — version to roll back to + runbook link; not optional for production releases
Feature description pattern: Not "added retry logic" (what you did) but "failed transactions auto-retry up to 3×... reduces payment failure UX by ~60%" (what it means for users/business)
Security patch best practice: State the CVE, severity, and behavioral change (e.g., "active sessions invalidated on deploy"). Alert your support team if this triggers customer logins.
2 / 4
You're writing a user-facing feature announcement for the product website/blog. The new feature is an AI-powered code review suggestion tool. Which announcement tone and structure is most appropriate?
Option C is a professional user-facing feature announcement:
User-facing announcement principles: 1. Lead with the problem you're solving — "code review is valuable but time-consuming" — before describing the solution 2. Describe in user terms, not technical implementation — "analyses PRs and surfaces common issues" not "transformer model" 3. Concrete benefit list — specific, action-oriented: "suggests fixes, not just flags" — this is a differentiator worth stating 4. How to enable — precise path (Settings → Code Review → ...) — removes friction to adoption 5. Honest early access framing — "early access" + "we'd love your feedback" — manages expectations and invites engagement 6. No hyperbole — "incredible!" without substance is marketing filler; the what/why/how is what creates confidence
The "before and after" pattern: User-facing features land better when you describe the user's world before the feature and after. "Before: you caught issues in review; After: AI catches them before review" creates context that "AI review is here!" cannot.
Technical detail placement: Give a feedback or docs link for users who want implementation details, rather than including them in the main announcement.
3 / 4
You need to write a CHANGELOG entry for version 2.4.0 that includes a breaking change: the `/api/v1/users` endpoint is deprecated in favor of `/api/v2/users`. Which entry format is most useful?
Option B follows the Keep a Changelog format, the de-facto standard for developer-facing changelogs:
Keep a Changelog structure: • Version number + ISO date (YYYY-MM-DD) • Sections in a defined order: Breaking Changes, Added, Changed, Deprecated, Removed, Fixed, Security • Each entry: one line, specific, with PR or bug reference
Breaking change documentation requirements: 1. Mark it prominently — "Breaking Changes" section first, bold label 2. State the removal timeline — "will be removed in v3.0.0" — gives integration owners a window 3. Provide the migration path — link to migration guide — reduces support load 4. Name the deprecation signal — "will return `Deprecation: true` header" — enables automated detection
Why PR links matter in CHANGELOGs: When a bug is reported in 6 months, the PR link takes you directly to the commit, reviewer discussion, and context. "Fixed race condition [#BUG-201]" with a PR link is 5× more useful than a description alone.
What KeepAChangelog.com says to avoid: • Diff dumps — "changed 47 files" is not a changelog • Git log contents — commits are for engineers reading git, changelogs are for all audiences
4 / 4
You need to send an email to your external API partners about the v1 API deprecation. These partners are technical but not on your internal team. Which email is most professional?
Option B is a complete external partner API deprecation notice:
External partner communication requirements (higher than internal): Partners have different codebases, release schedules, and may not check your CHANGELOG or Slack. External notices must be: 1. Explicit subject line with action required + timeline — "Action Required" signals urgency; "Q3 2024" targets planning cycles 2. What's changing — specific endpoint path, not "some API stuff" 3. What they need to do — the exact migration path, what's functionally equivalent vs. changed 4. The timeline with milestones — three phases (header warning → body warning → removal) gives them windows to detect and respond 5. Migration guide link — not just "check the docs" 6. Support path — email or ticket; makes you reachable
Legal and SLA considerations: For enterprise partners with API SLAs, 6 months minimum notice for breaking changes is common. For public APIs, 12 months is standard practice. Always check your API agreement or ToS before choosing the removal date.
Response rate improvement tips: • "Action Required" in subject line significantly improves open rates • Follow up 30 days before removal with a second notice to integrations that haven't migrated (check via header/log analytics)