sdk/pkg/analyzer/doc/implementation/releasing.md

Releasing the analyzer package and related packages

The 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),

Depending on unreleased code

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.

The analyzer and _fe_analyzer_shared packages

The _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:

• Commit that prepares analyzer 7.4.0 and _fe_analyzer_shared 81.0.0: https://github.com/dart-lang/sdk/commit/1f4fddd023ee9fe2c5565b5606b3f7bb7be6287b
• Commit that prepares analyzer 7.4.1 and _fe_analyzer_shared 82.0.0: https://github.com/dart-lang/sdk/commit/f8399893021b017ee57edbda49f5fec9db57b1bc

The analyzer_plugin and analyzer packages

The 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.

The analyzer_testing and analyzer packages

The 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.

The analysis_server_plugin and analyzer packages

The 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.

Workflow: Start a new minor version

To start a new minor version for the analyzer and related packages, follow these steps.

1. Update analyzer:

   • Edit pkg/analyzer/pubspec.yaml.
   • Set the version to the next minor dev version (e.g., 10.0.0 -> 10.1.0-dev).
   • Update pkg/analyzer/CHANGELOG.md to add a new section for the new version.
   • Add "Internal changes only" as a placeholder.

2. Update analyzer_plugin:

   • Edit pkg/analyzer_plugin/pubspec.yaml.
   • Set the version to the next patch dev version.
   • Update the analyzer dependency to be the exact version from step 1 (e.g., 10.1.0-dev).
   • Update pkg/analyzer_plugin/CHANGELOG.md to add a new section for the new version.

3. Update analyzer_testing:

   • Edit pkg/analyzer_testing/pubspec.yaml.
   • Update the analyzer dependency to be the exact version from step 1.
   • Set the version to the next patch dev version.
   • Update pkg/analyzer_testing/CHANGELOG.md to add a new section for the new version.

4. Update analysis_server_plugin:

   • Edit pkg/analysis_server_plugin/pubspec.yaml.
   • Set the version to the next patch dev version.
   • Update the analyzer dependency to be the exact version from step 1.
   • Update the analyzer_plugin dependency to be the exact version from step 2.
   • Update pkg/analysis_server_plugin/CHANGELOG.md to add a new section for the new version.

5. Prepare the commit message: see git 98c4f54c0f56b0f08d3fa7d5ddf4bcaf905764ff as example.

Workflow: Start a new major version

To start a new major version for the analyzer and related packages, follow these steps.

1. Update analyzer:

   • Edit pkg/analyzer/pubspec.yaml.
   • Increment the major version (e.g., 9.0.0 -> 10.0.0-dev).
   • Update pkg/analyzer/CHANGELOG.md to add a new section for the new version.
   • Add "Internal changes only" as a placeholder.

2. Update analyzer_plugin:

   • Edit pkg/analyzer_plugin/pubspec.yaml.
   • Set the version to the next patch dev version.
   • Update the analyzer dependency to allow the new major version (e.g., ^10.0.0-0).
   • Update pkg/analyzer_plugin/CHANGELOG.md to add a new section for the new version.

3. Update analyzer_testing:

   • Edit pkg/analyzer_testing/pubspec.yaml.
   • Set the version to the next patch dev version.
   • Update the analyzer dependency to allow the new major version (e.g., ^10.0.0-0).
   • Update pkg/analyzer_testing/CHANGELOG.md to add a new section for the new version.

4. Update analysis_server_plugin:

   • Edit pkg/analysis_server_plugin/pubspec.yaml.
   • Set the version to the next patch dev version.
   • Update the analyzer dependency to allow the new major version (e.g., ^10.0.0-0).
   • Update the analyzer_plugin dependency to be the exact version from step 2.
   • Update pkg/analysis_server_plugin/CHANGELOG.md to add a new section for the new version.

5. Prepare the commit message: see https://dart-review.googlesource.com/c/sdk/+/444924 as example.

Workflow: Prepare a release

To prepare the packages for publishing, follow these steps.

1. Update _fe_analyzer_shared:

   • Edit pkg/_fe_analyzer_shared/pubspec.yaml.
   • Increment the major version (e.g., 92.0.0 -> 93.0.0).

2. Update analyzer:

   • Edit pkg/analyzer/pubspec.yaml.
   • Set the version to the release version (e.g., remove -dev or increment).
   • Update the _fe_analyzer_shared dependency to match the new version from step 1 (e.g., ^93.0.0).
   • Update pkg/analyzer/CHANGELOG.md to set the version for the release entry.

3. Update analyzer_plugin:

   • Edit pkg/analyzer_plugin/pubspec.yaml.
   • Set the version to the release version.
   • Update the analyzer dependency to be the exact version from step 2 (e.g., 10.0.0).
   • Update pkg/analyzer_plugin/CHANGELOG.md to set the version for the release entry.

4. Update analyzer_testing:

   • Edit pkg/analyzer_testing/pubspec.yaml.
   • Set the version to the release version.
   • Update the analyzer dependency to be the exact version from step 2.
   • Update pkg/analyzer_testing/CHANGELOG.md to set the version for the release entry.

5. Update analysis_server_plugin:

   • Edit pkg/analysis_server_plugin/pubspec.yaml.
   • Set the version to the release version.
   • Update the analyzer dependency to be the exact version from step 2.
   • Update the analyzer_plugin dependency to be the exact version from step 3.
   • Update pkg/analysis_server_plugin/CHANGELOG.md to set the version for the release entry.

6. Prepare the commit message: see git ef20543995d1a1052993881c62d6525e426336e7 as example.