Azure App Configuration Release Notes

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.