Deprecation Julep

[simonbyrne]

We need an explicit policy for how deprecations will be handled post-1.0. Some options are:

1. Allow them in minor releases, removed next minor release
2. Allow them in minor releases, removed next major release
3. Allowed only in major release, removed next minor release
   • Could be added in minor releases, but hidden have --depwarn=no by default.

We can use this issue for preliminary discussion until the appropriate Julep is written.

[tkoolen]

Sorry if this is a little unrelated to the question in the issue description, but on the topic of deprecations, I was wondering whether it would be a good idea to centralize the process a bit more. Currently:

1. a breaking change is made in Base. @depwarns are created and News.MD is updated.
2. somebody (else?) needs to make a corresponding change in Compat.jl
3. somebody (else?) needs to make a corresponding change in Deprecations.jl

Are people happy with this procedure? Perhaps developer overhead could be reduced by centralizing these in JuliaLang/julia.

[simonbyrne]

That certainly seems like it should be within scope of the Julep.

[JeffBezanson]

It seems to me that by its nature Compat.jl needs to be versioned separately from JuliaLang/julia. Deprecations.jl could be moved though.

What I think we need is the ability to add deprecations at any time, but have them be silent by default (either by making no the default for --depwarn, or by adding a new silent deprecation mechanism). There are also two kinds of deprecations: (1) changes like renamings, that can coexist with the new version, and (2) deprecations that need to be removed to get the new behavior (e.g. changing the meaning of an existing name or syntax).

How about this: in 2.0-alpha we turn all deprecations from silent to noisy. Then we try to have a fairly long alpha, beta and RC process. In 2.0.0-final, type (2) deprecations are removed to expose the new behaviors. Type (1) deprecations remain, and are removed in 3.0-alpha. So in general:

• version N.x: add silent deprecations
• version (N+1).0-alpha: remove type 1 deprs from version (N-1), make version N deprecations noisy.
• version (N+1).0-final: remove type 2 deprs from version N

[JeffBezanson]

In fact I suspect we do need a silent deprecation mechanism (which might consist only of marking things as such in the documentation), since changing the code in any way (e.g. to call depwarn or check a flag) could have overhead.

[StefanKarpinski]

Alternate proposal is to have deprecations in 2.0-final and then deleting the deprecations in 2.1 and adding the changed behaviors then. I know that's a bit less satisfying but we've also seen that people keep asking about names/behaviors that changed because they're skipping 0.7 and going straight to 1.0.

[IainNZ]

@simonbyrne your option 1 would violate "semantic versioning" principle of backwards compatibility for major releases right? Or am I misreading?

[JeffBezanson]

It seems to me people would be even more annoyed if going from 2.0 to 2.1 were breaking, instead of just 2.0 being breaking.

[simonbyrne]

Here is the semver statement: https://semver.org/#how-should-i-handle-deprecating-functionality

[mauro3]

From https://github.com/JuliaLang/Juleps/issues/51#issuecomment-412648578:

• version (N+1).0-final: remove type 2 deprs from version N

This would mean that these type-2 deprs never error, as they did until now, right? Would it make sense to also have a version (N+1).0-pre-final which errors instead of exposing the new behavior?

[JeffBezanson]

I wrote that they would error in (N+1).0-alpha

[simonbyrne]

Also within scope is the stability of experimental features, and the role of the Future.jl stdlib.

[StefanKarpinski]

I've often imagined doing using Julia 1.3 (or something like that) to indicate that you are following the best practices of Julia 1.3 and higher, which would warn/error on anything that was valid in 1.0-1.2 but has been replaced by something newer since then. This would have to be per-file or per-module.