Upgrade guide for SpecialFunctions 2.0

[KristofferC]

SpecialFunctions 2.0 was just released which is a breaking version. People wanting to upgrade to the new version want to see what has been breaking, how they can check that they are affected and what code they have to change. I would suggest having a prominent upgrade guide in the README and documentation to help people depending on SpecialFunctions understand what they need to do to be compatible with 2.0.

An example could be https://github.com/JuliaLang/PackageCompiler.jl#upgrading-from-packagecompiler-10 + https://julialang.github.io/PackageCompiler.jl/dev/#Upgrading-from-PackageCompiler-1.0.

Also, since this package is so heavily used (300+ dependendees)it is likely to take a long time for the ecosystem to move over to the new version. I would therefore request future bug fixes to be backported to 1.x until that has happened.

[oxinabox]

Am I correct in saying the upgrade guide should basically say:

SpecialFunctions 2.0 has been released.
It only has a single breaking change. #297
The removal of the type piracy of Base.factorial(x::Number)=gamma(x + 1).
For most users this change will not break anything; but for uses of factorial it might.
Be warned: as the previous overload of factorial was type piratical, it is possible for your code to have been using it without a direct dependency on SpecialFunctions.jl, as long as it is loaded.
As such random things might break because of this.
We are sorry this wasn't caught earlier, the mistake was made 4 years ago when code was moved out of Base.

• If your code does not use factorial then change your compat to e.g. "1.8.1, 2"
• If your code does use factorial then if it is calling factorial on an Integer leave it alone, otherwise change it to calling gamma

[stevengj]

I filed PRs with all of SpecialFunctions' direct dependencies to upgrade their Project.toml. The only package that actually needs to update its code looks like JuliaStats/Distributions.jl#1436

[cossio]

Perhaps @oxinabox comment can be put on the README?
I was just having some upgrade conflicts due to to SpecialFunctions 2.0, and had to do a bit of digging to see where the breaking change was. I agree with @KristofferC comment here. Even if the change is minor, it's breaking and should be clearly explained in a more prominent place than an issue.

[devmotion]

I just noticed @oxinabox's suggestion is not completely correct, it was not

The removal of the type piracy of Base.factorial(x::Number)=gamma(x).

but

The removal of the type piracy of Base.factorial(x::Number)=gamma(x + 1).

I thought it would be good to point this out to avoid that users just replace factorial with gamma.