Adding a parameter breaks subclasses.

[mosuem]

Imagine the following setting in a package:foo.

Before

abstract class A {
  void someMethod();
}

After

abstract class A {
  void someMethod([int? i]);
}

This should be a breaking change as A is not final, but seems to be recognized as CE02 - minor. This was noticed in dart-lang/http#1725, when running

cd http/pkgs/http2
gh pr checkout 1725
dart-apitool diff --new . --old pub://http2

No breaking changes!
Non-Breaking changes
├─┬ Class TransportConnection
│ └─┬ Method terminate
│   └── Parameter "message" added (CE02) (minor)
├─┬ Class ClientTransportConnection
│ └─┬ Method terminate
│   └── Parameter "message" added (CE02) (minor)
└─┬ Class ServerTransportConnection
  └─┬ Method terminate
    └── Parameter "message" added (CE02) (minor)

[devmil]

@mosuem
Yes, this is a tricky problem as there is no way for dart_apitool to decide between

• API: interface is meant to be consumed (adding optional parameters is not breaking) and
• SPI: interface is meant to be implemented by the consumer (adding optional parameters is breaking)

There are some attempts in dart_apitool to track type usages (so if an interface is used as input somewhere there is an increased chance that we have a SPI situation).
In that specific case that is linked I think the Connection is not passed into the http2 package anywhere, right? So dart_apitool treats it as API.

[mosuem]

But Dart provides class modifiers for that distinction, right? If I can implement an interface, then this is a breaking change.

[devmil]

yes but I'm not sure if we can rely on those tbh. They cause issues with mocking and packages might not have updated to really use them

[mosuem]

True, I am definitely guilty of using them not often enough. But their existence would swing the pendulum a bit towards erring on the side of caution here in my mind - I would rather get a note to increase the major version and ignoring that than the other way around.
Also, the info message might contain a if you do not consider this breaking, make the class final or similar.

[devmil]

I think we could improve the already existing "requiredness" option (that goes into the other direction) to also allow to be more strict