dart_apitool improvements

Software development

dart_apitool improvements

There has been some new development in dart_apitool.

I got some feedback from our internal “My BMW” app teams and from the Flutter community so dart_apitool has received some extensions, improvements and fixes the last months:

Flutter cache location changed

While playing around with Flutter 3.7.0 I realized that the cache location of Dart packages can be a different one.
Sometimes (I don’t know why exactly, yet) flutter stores the packages not in the .pub-cache/hosted/pub.dartlang.org/... folder like it did previously but in the .pub-cache/hosted/pub.dev/... folder. 🤷‍♂️
Looks like some fixing has happened there as pub.dev is the official pub URL.
My assumption is that existing packages won’t get moved but new packages are stored in the new folder, but this needs further testing.
Dart_apitool now accounts for that and there is a hotfix version 0.10.2 to fix that issue.

Path dependency support

In the “My BMW” app package structure we have some cases that use path dependency while development that get turned into pub dependencies on release.
As dart_apitool runs pre-release (hopefully at least 😉) it has to deal with those path dependencies.
Dart_apitool copies the project to analyze into a temporary directory to do some tweaks to it without affecting the sources (e.g. removing analyzer options to not limit the Analyzer scope). If that project contains path dependencies reaching outside of the project location then this approach fails as those path dependencies are no longer reachable inside the temporary directory.
Dart_apitool now has a new flag --[no-]include-path-dependencies that defaults to off that analyzes the path dependencies tree and copies the whole directory structure into the temporary directory if needed.
Thanks Adam for implementing this improvement!

@experimental flag support

I realized that some (especially dart team) packages use the @experimental flag to mark APIs that are likely to go away or change.
Dart_apitool now takes this flag into account when deciding what type of change it has found.
👉 Experimental marked API elements don’t lead to braking changes.

Fixing local package ref handling

SupposedlySam found out that dart_apitool logs some errors in his package. After analyzing this it turned out that there has been a bug in dart_apitool that got triggered on local package references.
So if a dart file exports other dart files via local package refs, like export 'package:firefuel/src/batch.dart' dart_apitool would not follow that export and log the mentioned error.
This was fixed with 0.11.1

Better dependency change handling

Another topic brought up by SupposedlySam was regarding dart_apitool’s handling dependency changes.
Dart_apitool only differentiated “breaking” and “non-breaking” changes.
“Breaking” changes led to requiring a major version bump while “non-breaking” changes led to requiring a minor version bump.
While this is correct for most of the changes, dependencies are special:
If a dependency got a major version bump then this is without question a “breaking” change. Adding dependencies as well.
But if a dependency got a compatible version bump or a dependency got removed then requiring a minor version bump is too much.
For this dart_apitool now differentiates “breaking”, “non-breaking (minor)” and “non-breaking (patch)” change types with dependencies being the only change that can make use of that new change type tier.


So quite some development is going on in dart_apitool.
Special thanks to Adam from BMW and SupposedlySam for filing issues and contributing to dart_apitool!