Google Git
Sign in
flutter/mirrors/flutter/abd8d37c999fa3c9ca71c2f0cfb98e6bf2201894^!/.
commit
abd8d37c999fa3c9ca71c2f0cfb98e6bf2201894
[log]
author
stuartmorgan-g <stuartmorgan@google.com>
Sun Jun 14 14:45:30 2026 -0400
committer
GitHub <noreply@github.com>
Sun Jun 14 18:45:30 2026 +0000
tree
fb16777c6a9a977f6b7943cb7fb664d88861b425
parent
601ed1be013a1deb31b44a15d0452eab71eee4e8 [diff]
Rework docs for flutter/packages changelogs (#187666)

Updating CHANGELOGs correctly is one of the most common issues for new
contributors in flutter/packages. The way the docs were written
highlights using the `NEXT` section for version-exempt changes first,
because it's unusual and specific to our repo, but given how common it
is for new contributors to use it when they shouldn't, it seems like
this structure is likely confusing for the people who most need the
docs.

This reworks the whole section to discuss the common case first, then
the uncommon case (now explicitly highlighted as uncommon) second. The
new structure is a little longer, but should hopefully be more clear,
which seems like a tradeoff worth trying given the frequency of issues.

Also includes some minor fixes I noticed while I was in the file
(grammar, inconsistent backticks for file names), and addition of
references to the new flutter/core-packages.
diff --git a/docs/ecosystem/contributing/README.md b/docs/ecosystem/contributing/README.md
index cda7ad1..3fdd223 100644
--- a/docs/ecosystem/contributing/README.md
+++ b/docs/ecosystem/contributing/README.md

@@ -1,14 +1,21 @@
-This page covers additional information that is specific to contributing to flutter/packages. If you aren't already familiar with the general guidance on Flutter contribution, start with [Tree hygiene](../../contributing/Tree-hygiene.md).
+This page covers additional information that is specific to contributing to flutter/packages and flutter/core-packages. If you aren't already familiar with the general guidance on Flutter contribution, start with [Tree hygiene](../../contributing/Tree-hygiene.md).
 
 ## Version and CHANGELOG updates
 
-Most changes need version and CHANGELOG change information; see below for details. Even version-exempt changes should often include a CHANGELOG entry, since some changes (e.g., certain updates to examples) that do not need to be published may still be of interest to clients of a package.
+Most changes need version and CHANGELOG change information; see below for details.
 
 In most cases, the easiest way to handle version and CHANGELOG updates is to use [the `update-release-info` repository command](https://github.com/flutter/packages/blob/main/script/tool/README.md#update-changelog-and-version). If you are adding a feature, use `--version=minor`, otherwise `--version=minimal` will almost always do the right thing.
 
 If you are not using `update-release-info`, you will need to determine whether the package you are changing uses the continuous or [batched](../release/README.md#batch-release) release model, and follow the appropriate instructions below. If the package has a top-level `ci_config.yaml` setting `release:batch:true`, then it uses batched release, otherwise it defaults to continuous release.
 
-*The repository CI errs on the side of false positives, so will sometimes flag a PR as needing a CHANGELOG entry even if the change is not relevant to clients. If a Flutter team member feels that the changes in a PR would not be relevant to package clients, they can leave a comment explaining why, and add the `override: no changelog needed` label to skip this check.*
+*Version-exempt changes should still include a CHANGELOG entry if they are relevant
+to package clients (for example, updating the minimum SDK version, or adding
+new example code to a page other than `main.dart`). The repository CI errs on
+the side of false positives, so will sometimes flag a PR as needing a CHANGELOG
+entry even if the change is not relevant to clients. If a Flutter team member
+feels that the changes in a PR would not be relevant to package clients, they
+can leave a comment explaining why, and add the `override: no changelog needed`
+label to skip this check.*
 
 ### CHANGELOG style
 
@@ -54,49 +61,71 @@
 
 #### CHANGELOG
 
-All version changes must have an accompanying CHANGELOG update. Version-exempt changes that need a CHANGELOG entry should use a special `NEXT` entry at the top of `CHANGELOG.md`:
-```
-## NEXT
+All version changes must have an accompanying `CHANGELOG.md` update. As noted
+above, version-exempt changes should also have a CHANGELOG entry if they are
+relevant to package clients.
 
-* Description of the change.
+- If you are using `update-release-info`, this will be handled correctly for you.
+- If you prefer to make the change manually, make sure to follow the relevant
+  instructions below, as well as the following additional style rules:
+  - Use `##` for the version line. A version line should have a blank line before and after it.
+  - Use `*` for individual items.
+    - Exception: When editing a file that already uses `-`, use that instead for local consistency.
 
-## 1.0.2
-...
-```
+##### Versioned change
 
-For manual changes to CHANGELOG.md for packages using continuous releases, the following additional style rules apply:
-- Use `##` for the version line. A version line should have a blank line before and after it.
-- Use `*` for individual items.
-  - Exception: When editing an existing CHANGELOG that uses `-`, use that instead for local consistency.
-
-##### Updating a CHANGELOG.md that has a `NEXT`
-
-*Note: If you are using `update-release-info`, this will be handled correctly for you.*
-
-If you are adding a version change to a CHANGELOG that starts with `NEXT`, and your change also doesn't require a version update, just add a description to the existing `NEXT` list:
-```
-## NEXT
-
-* Description of your new change.
-* Existing entry.
-
-## 1.0.2
-...
-```
-
-If your change does require a version change, do the same, but then replace `NEXT` with the new version. For example:
+For the common case where you are making a versioned change and there is no
+`## NEXT` section in the `CHANGELOG.md`, simply add the new version as the topmost
+section:
 
 ```
 ## 1.0.3
 
 * Description of your new change.
-* Existing entry.
 
 ## 1.0.2
 ...
 ```
 
-If you leave `NEXT` when adding a version change, automated tests for your PR will fail.
+If there is a `## NEXT` section at the top of the `CHANGELOG.md` (from a
+previous version-exempt change; see below), convert that section into a
+numbered release section, adding your entry as the first line:
+
+```
+## 1.0.3
+
+* Description of your new change.
+* Previous version-exempt entry.
+
+## 1.0.2
+...
+```
+
+##### Version-exempt change
+
+For the rare case of a version-exempt change, use a special `NEXT` entry at the
+top of `CHANGELOG.md`:
+
+```
+## NEXT
+
+* Description of your new version-exempt change.
+
+## 1.0.2
+...
+```
+
+If there is already a `NEXT` section, add your change to the existing list:
+
+```
+## NEXT
+
+* Description of your new version-exempt change.
+* Previous version-exempt entry.
+
+## 1.0.2
+...
+```
 
 #### FAQ
 
@@ -108,7 +137,7 @@
 
 ### Batched release
 
-Packages that receive a large number of PRs use a batched release model, both to avoid constant conflicts in CHANGELOG.md and pubspec.yaml, and to avoid constantly having new releases on pub.dev. For packages using batched release, any change that requires a CHANGELOG entry requires a new file in the package's `pending_changes/` directory. To do this without `update-release-info`, copy `template.yaml` to a new file with a descriptive name in the same directory, then edit it to have the correct CHANGELOG entry and version type.
+Packages that receive a large number of PRs use a batched release model, both to avoid constant conflicts in `CHANGELOG.md` and `pubspec.yaml`, and to avoid constantly having new releases on pub.dev. For packages using batched release, any change that requires a CHANGELOG entry requires a new file in the package's `pending_changes/` directory. To do this without `update-release-info`, copy `template.yaml` to a new file with a descriptive name in the same directory, then edit it to have the correct CHANGELOG entry and version type.
 
 ### Breaking changes
 
@@ -121,7 +150,7 @@
 
 ## Dependencies
 
-We try to minimize external package dependencies as much as possible, where "external" means packages that are not generally within the control of the Flutter or Dart teams (Examples of non-external packages include `sdk:` dependencies, packages in flutter/packages, and packages published by dart.dev), or by an organization with a track record of strong support for both engineering best practices and Flutter. This is for several reasons:
+We try to minimize external package dependencies as much as possible, where "external" means packages that are not generally within the control of the Flutter or Dart teams (examples of non-external packages include `sdk:` dependencies, and packages published by flutter.dev or dart.dev), or by an organization with a track record of strong support for both engineering best practices and Flutter. This is for several reasons:
 - Maintainability:
     - We have a policy of always supporting Flutter `master`; if we can't guarantee that fixes for breaking changes can be landed immediately in dependencies, it can block our roller.
     - If a package is abandoned by its authors, we will have to fork or migrate in order to unblock the entire repository.
@@ -216,7 +245,7 @@
 
 If a new plugin is being created, or a plugin is being extended to a new platform, it's fine to require a newer OS version if there is a good reason to do so. For instance, if it would require adding significant already-deprecated codepaths that would cause a maintenance burden, it may not be worth supporting older OS versions.
 
-For existing plugins, dropping support for OS versions that are still supported by Flutter (or supported by older versions of Flutter that are still within the allowance of the package's pubspec.yaml Flutter constraint) is **very disruptive**: because `pub` does not have information about OS version support, dropping previously-supported OS versions is build breaking for clients. There are three possible approaches to dropping an OS version from an existing plugin:
+For existing plugins, dropping support for OS versions that are still supported by Flutter (or supported by older versions of Flutter that are still within the allowance of the package's `pubspec.yaml` Flutter constraint) is **very disruptive**: because `pub` does not have information about OS version support, dropping previously-supported OS versions is build breaking for clients. There are three possible approaches to dropping an OS version from an existing plugin:
 1. Wait for Flutter to drop that version, then set the minimum SDK version accordingly before/while dropping the OS version in the plugin. This means that a client still targeting the dropped version can never resolve to the version of the package that dropped support, so it is a no-op for clients. This is the **strongly preferred** approach.
 2. Drop the version as a breaking change. Keep in mind that this must be a breaking change not only for the implementation package, but also for the app-facing package when updating to use the new major version of the implementation package, so should be discussed with the ecosystem team in advance. This approach ensures that clients have appropriate breaking change notification, and have to opt in to the new version.
 3. While it is **strongly discouraged**, in rare cases we have dropped OS version support without a major version change. This should be done only if a major version change would be disruptive to the ecosystem and the OS version drop cannot be delayed until after Flutter has dropped it. For example, if continuing to support an older OS version would require continuing to use an older version of an SDK that has a significant security vulnerability, this approach could be warranted. This should only be done if the costs of one of the two previous approaches is so high that causing unexpected build breakage for plugin clients is a better outcome.
@@ -266,7 +295,7 @@
 
 We are investigating ways to streamline this, but currently the process for a multi-package PR is:
 
-1. Create a PR that has all the changes, and update the pubspec.yaml files to have path-based dependency overrides. This can be done with the [plugin repo tool](https://github.com/flutter/packages/blob/main/script/tool/README.md)'s `make-deps-path-based` command, targeting any dependency packages changed in the PR. For instance, for an Android-specific change to `video_player` that required platform interface changes as well:
+1. Create a PR that has all the changes, and update the `pubspec.yaml` files to have path-based dependency overrides. This can be done with the [plugin repo tool](https://github.com/flutter/packages/blob/main/script/tool/README.md)'s `make-deps-path-based` command, targeting any dependency packages changed in the PR. For instance, for an Android-specific change to `video_player` that required platform interface changes as well:
     ```
     $ dart run script/tool/bin/flutter_plugin_tools.dart make-deps-path-based --target-dependencies=video_player_platform_interface,video_player_android
     ```
@@ -375,7 +404,7 @@
 
 ### In-package platform channels
 
-All implementations should use in-package platform channels, for the reasons outlined in [the proposal document](https://flutter.dev/go/platform-channels-in-federated-plugins). Most plugins that predate this policy and have a legacy "shared method channel" default implementation in the platform interface package, but it is not be used by any first-party implementations.
+All implementations should use in-package platform channels, for the reasons outlined in [the proposal document](https://flutter.dev/go/platform-channels-in-federated-plugins). Many plugins that predate this policy have a legacy "shared method channel" default implementation in the platform interface package, but it is not used by any first-party implementations.
 
 ### Platform exception handling