manual: methods: new section on avoiding ambiguity: "playing nicely"

[nsajko]

The fact that an important (for the ecosystem) registered package failed to follow the advice/rule provided in the change is evidence to the claim that adding these docs is important. Ref:

• defining a method of a generic comparison with one argument unconstrained in a package is a bug JuliaAlgebra/MultivariatePolynomials.jl#310

Fixes #55866

[adienes]

I think the information & reminder of the possibility of ambiguity could definitely be useful to have in the docs. But in my opinion I would phrase it more neutrally-informatively as a reminder rather than as an admonition. that would mean bringing the tone from "don't do this as it's impolite" ---> "if you do this, ambiguities can occur"

after all, maybe the package authors are completely fine with creating ABExt.jl to deal with the ambiguity of ==(::A, ::B)

[nsajko]

The issue is such: an "impolite" package causes method ambiguity with respect to an unbounded number of potential packages. We can't expect either:

• for the impolite package to depend on packages that don't exist yet
• new packages to depend on the impolite package, as, there again may be an unbounded number of impolite packages, some of which will only exist in the future

So the gotcha you mention, where the two packages resolve the ambiguity among themselves, without considering the rest of the ecosystem, is valid only when these two packages are in a special relationship where one of the two packages (the dependent package) depends (either strongly or weakly) on the other package (the dependency package) and the dependent package is allowed to access private parts of the dependency package. Such a relationship indicates that the ownership between the two packages is the same or shared. And that's why I included the "unrelated ownership" wording, although the clarity may need to be improved still.

[nsajko]

Thinking about the gotcha more, I think it would be fine not to mention it in the docs. The gotcha is basically "I defined a method that causes ambiguity, but you don't need to care about it because an ambiguous call may only happen if you access my internals". However that's still impolite because of causing Aqua.jl noise in my opinion.