pkg/analyzer/doc/implementation/releasing.md
analyzer package and related packagesThe analyzer package is released simultaneously with several other packages.
This is because we generally do not have tooling in the Dart SDK repository
that shows us when code from a given package starts using unreleased
functionality from the analyzer package. Similarly, we do not have tooling
that shows us when code from the analyzer package starts using unreleased
functionality from the _fe_analyzer_shared package.
This document describes the publishing policies for the analyzer package and
related packages which are developed in the Dart SDK repository, including:
_fe_analyzer_shared (source, pub package),analyzer (source, pub package),analyzer_plugin (source, pub package),analyzer_testing (source, (not yet published)),analysis_server_plugin (source, pub package),The main concern in these release policies is that all of these packages are developed in the Dart SDK repository, and so they all depend on each other "at main branch HEAD." We also don't track when one package depends on new, unreleased code in another package. Any commit that touches one package and a dependant package could be introducing a dependency on unreleased code. Because we do not manually track commits like this (and even if we did, it would be error-prone), it should be assumed that at any given point in time, code in one of these packages depends on unreleased code in another package. To safely keep such packages in sync, they should be released simultaneously.
analyzer and _fe_analyzer_shared packagesThe _fe_analyzer_shared package is published to pub, so that the analyzer
package can use it, but it is not meant to be consumed by any other packages on
pub. The policy is to just call every new release of the
_fe_analyzer_shared package a breaking release. The _fe_analyzer_shared
package must be released each time the analyzer package is released, with a
major version bump. The version of the analyzer package being released must
then depend on exactly that new version of the _fe_analyzer_shared package.
(Technically a caret dependency, like _fe_analyzer_shared: ^82.0.0 would
work, but it doesn't really make sense given that we only version the
_fe_analyzer_shared package with major version releases.)
One way the _fe_analyzer_shared package discourages anyone from depending on
it directly is that the lib directory contains no files or directories except
the src directory. Importing directly from the _fe_analyzer_shared
package's lib/src directory is a strong signal that a user is doing something
ill-advised.
See for example:
_fe_analyzer_shared 81.0.0:
https://github.com/dart-lang/sdk/commit/1f4fddd023ee9fe2c5565b5606b3f7bb7be6287b_fe_analyzer_shared 82.0.0:
https://github.com/dart-lang/sdk/commit/f8399893021b017ee57edbda49f5fec9db57b1bcanalyzer_plugin and analyzer packagesThe analyzer_plugin package is published to pub for developers of legacy
analyzer plugins and developers of new analyzer plugins. The code in the
analyzer_plugin package depends on private implementation code of the
analyzer package, so it must be released whenever the analyzer package is
released.
The versioning of the analyzer_plugin package can follow basic semantic
versioning based on its own API.
The analyzer_plugin package must depend on the analyzer package with an
exact version constraint.
analyzer_testing and analyzer packagesThe analyzer_testing package will be published to pub for developers of new
analyzer plugins. The code in the analyzer_testing package depends on private
implementation code of the analyzer package, so it must be released whenever
the analyzer package is released.
The versioning of the analyzer_testing package can follow basic semantic
versioning based on its own API.
The analyzer_testing package must depend on the analyzer package with an
exact version constraint.
analysis_server_plugin and analyzer packagesThe analysis_server_plugin package will be published to pub for developers of
new analyzer plugins. The code in the analysis_server_plugin package
depends on private implementation code of the analyzer package, so it must be
released whenever the analyzer package is released.
The versioning of the analysis_server_plugin package can follow basic
semantic versioning based on its own API.
The analysis_server_plugin package must depend on the analyzer package with
an exact version constraint. It must also depend on the analyzer_plugin
package with an exact version constraint.
To start a new minor version for the analyzer and related packages, follow these steps.
Update analyzer:
pkg/analyzer/pubspec.yaml.dev version (e.g., 10.0.0 -> 10.1.0-dev).pkg/analyzer/CHANGELOG.md to add a new section for the new version.Update analyzer_plugin:
pkg/analyzer_plugin/pubspec.yaml.dev version.analyzer dependency to be the exact version from step 1 (e.g., 10.1.0-dev).pkg/analyzer_plugin/CHANGELOG.md to add a new section for the new version.Update analyzer_testing:
pkg/analyzer_testing/pubspec.yaml.analyzer dependency to be the exact version from step 1.dev version.pkg/analyzer_testing/CHANGELOG.md to add a new section for the new version.Update analysis_server_plugin:
pkg/analysis_server_plugin/pubspec.yaml.dev version.analyzer dependency to be the exact version from step 1.analyzer_plugin dependency to be the exact version from step 2.pkg/analysis_server_plugin/CHANGELOG.md to add a new section for the new version.Prepare the commit message: see git 98c4f54c0f56b0f08d3fa7d5ddf4bcaf905764ff as example.
To start a new major version for the analyzer and related packages, follow these steps.
Update analyzer:
pkg/analyzer/pubspec.yaml.9.0.0 -> 10.0.0-dev).pkg/analyzer/CHANGELOG.md to add a new section for the new version.Update analyzer_plugin:
pkg/analyzer_plugin/pubspec.yaml.dev version.analyzer dependency to allow the new major version (e.g., ^10.0.0-0).pkg/analyzer_plugin/CHANGELOG.md to add a new section for the new version.Update analyzer_testing:
pkg/analyzer_testing/pubspec.yaml.dev version.analyzer dependency to allow the new major version (e.g., ^10.0.0-0).pkg/analyzer_testing/CHANGELOG.md to add a new section for the new version.Update analysis_server_plugin:
pkg/analysis_server_plugin/pubspec.yaml.dev version.analyzer dependency to allow the new major version (e.g., ^10.0.0-0).analyzer_plugin dependency to be the exact version from step 2.pkg/analysis_server_plugin/CHANGELOG.md to add a new section for the new version.Prepare the commit message: see https://dart-review.googlesource.com/c/sdk/+/444924 as example.
To prepare the packages for publishing, follow these steps.
Update _fe_analyzer_shared:
pkg/_fe_analyzer_shared/pubspec.yaml.92.0.0 -> 93.0.0).Update analyzer:
pkg/analyzer/pubspec.yaml.-dev or increment)._fe_analyzer_shared dependency to match the new version from step 1 (e.g., ^93.0.0).pkg/analyzer/CHANGELOG.md to set the version for the release entry.Update analyzer_plugin:
pkg/analyzer_plugin/pubspec.yaml.analyzer dependency to be the exact version from step 2 (e.g., 10.0.0).pkg/analyzer_plugin/CHANGELOG.md to set the version for the release entry.Update analyzer_testing:
pkg/analyzer_testing/pubspec.yaml.analyzer dependency to be the exact version from step 2.pkg/analyzer_testing/CHANGELOG.md to set the version for the release entry.Update analysis_server_plugin:
pkg/analysis_server_plugin/pubspec.yaml.analyzer dependency to be the exact version from step 2.analyzer_plugin dependency to be the exact version from step 3.pkg/analysis_server_plugin/CHANGELOG.md to set the version for the release entry.Prepare the commit message: see git ef20543995d1a1052993881c62d6525e426336e7 as example.