Release Notes Authoring Skill

This skill guides the authoring of customer-facing release notes for Azure App Configuration libraries and providers. Release notes live in releaseNotes/ and are the primary way customers learn about new versions.

Key Principle

Release notes are for customers, not engineers. Every entry should help a customer decide whether to upgrade and understand what changed from their perspective.

File Location & Naming

• All release notes go in releaseNotes/ in this repository, even if the library has its own repo.
• One Markdown file per product (e.g., MicrosoftExtensionsConfigurationAzureAppConfiguration.md).
• If adding release notes for a new product, create a new file in releaseNotes/.

File Structure

Each release notes file follows this structure:

# Product Name

[Source code][source_code] | [Package (NuGet/npm/PyPI)][package] | [Samples][samples]

## {version} - {Month} {Day}, {Year}

### Breaking Changes

### Enhancements

### Bug Fixes

<!-- Reference links at bottom of file -->
[source_code]: https://...
[package]: https://...
[samples]: https://...

Version & Date Format

• Use the format: ## {version} - {Month} {Day}, {Year}
• Use the full month name, never abbreviations.
• Examples:
  • ## 7.0.0 - November 21, 2023
  • ## 2.4.0 - February 17, 2026
  • ## v1.5.0 - February 14, 2026 (Go uses the v prefix)
  • ## 8.6.0-preview - February 26, 2026 (preview/beta versions)
• Sort entries in reverse chronological order (newest first).

Categories

Organize changes under these headings. Omit a category if it has no entries for that release.

Breaking Changes

Reserved for changes that require customers to modify their code or configuration.

• Always explain why the breaking change was made.
• Always explain how to migrate from the old behavior to the new one.
• Example:

  Removed IConfigurationRefresher.SetDirty API in favor of IConfigurationRefresher.ProcessPushNotification API for push-model based configuration refresh. Unlike the SetDirty method, the ProcessPushNotification method guarantees that all configuration changes up to the triggering event are loaded in the following configuration refresh. For more details on the ProcessPushNotification API, refer to this tutorial.

Enhancements

New features, capabilities, or improvements.

• Describe what new scenarios are enabled and how to take advantage of them.
• Don't just name a new API — explain what it lets customers do.
• Include brief code snippets when they help illustrate usage.
• Example:

  Added health check integration for Microsoft.Extensions.Diagnostic.HealthChecks. You can call AddAzureAppConfiguration on IHealthCheckBuilder to register a health check for the Azure App Configuration provider. #644

  builder.Services
     .AddHealthChecks()
     .AddAzureAppConfiguration();

Bug Fixes

Fixes for issues customers may have encountered.

• Describe the symptom, not the implementation fix. Customers need to know if the bug affected them.
• Bad: "Added a call to ConfigureAwait(false) in LoadKeyValuesRegisteredForRefresh"
• Good: "Fixed a bug where ASP.NET Framework applications may fail to refresh their configuration."
• Example:

  Fixed a bug where calls to FeatureFlagOptions.Select were ignored if they were followed by a call to either AzureAppConfigurationOptions.Select or AzureAppConfigurationOptions.SelectSnapshot. #628

Linking to Issues and PRs

• Always link each change to a GitHub issue or PR.
• Prefer linking to issues over PRs — issues provide more context and already link to the PR.
• Use the format: [#123](https://github.com/org/repo/issues/123)
• Place the link at the end of the bullet point.
• Example:

  Added the following new API for additional App Configuration geo-replication support. #385

Writing Style

• Use past tense: "Added support for…", "Fixed a bug where…", "Removed the API…"
• Write from the customer's perspective, not the developer's.
• Be concise but informative — one to two sentences per entry is typical.

What to Exclude

Do not include changes that are not meaningful to customers:

• Internal code refactoring
• Telemetry additions or changes
• Test improvements
• CI/CD pipeline changes
• Dependency bumps that don't affect customer behavior (unless they fix a customer-facing issue)

Special Cases

Preview / Beta Releases

• Include preview and beta versions in the same file, interleaved chronologically.
• Use the full version string: ## 8.6.0-preview - February 26, 2026
• Preview/beta releases are cumulative — each one includes all changes from previous previews in that series. List all changes in every preview entry; duplicates across preview entries are expected.
• The first stable release also re-lists all changes that were introduced across its preview/beta cycle. Do not omit items just because they appeared in a prior preview.

Delisted Releases

• Mark delisted versions in the heading: ## 4.2.1 - July 9, 2025 (Delisted)
• Explain why the release was delisted and link to the tracking issue.

Stable Releases That Graduate Preview Features

• Note which features are graduating from preview: "This is the first stable release of the SetClientFactory API introduced in 8.2.0-preview."

Product Reference

Use this table to determine the correct release notes file, GitHub repo (for issue/PR links), and package registry for each product. This information is also available in the main README.

Configuration Providers

Feature Management Libraries

Platform & Tools

Legacy (Deprecated)