[PROPOSAL] Formal policy around preserving dead methods with a warning

[Matt Mackall]

On Wed, 2015-12-02 at 16:18 -0500, Augie Fackler wrote:
> Formally, Mercurial offers no API stability. That said, we've found a
> few times where it's cheap for us to preserve a backwards
> compatibility shim for extension authors so they have a full release
> cycle to update. This also makes life slightly easier for extension
> authors[0] when Mercurial is moving very rapidly, as it has been for
> the last few releases. We propose the following compromise policy:
> 
>  * When convenient, widely used functions will be preserved with a
> devel-warning for no more than one release cycle.
>  * The devel-warning will include a specific "no later than" version
> number after which the function will be removed. This version number
> should typically be no more than one release in the future (eg if
> we're developing 3.6 now, then when we start on 3.7 the function
> should die).
> 
> Examples of where we have done (or would have done) this:
>  * repo.opener -> repo.vfs upgrade (was violent breakage for
> extensions when it happened, was easy to maintain compatibility as
> the API was the same)
>  * dirstate.write() without a transaction (was done, needs to be
> removed)
> 
> Example of an upcoming change:
> bookmarks.write() is transactionally unsound and should die. Its only
> user left in core is a test.

I'm not convinced that this is going to be a win, but I'm going to let
you try it anyway. Wants a really easy-to-use helper function and maybe
a test to find stale calls.

I think what will usually happen in practice is:

- we'll deprecate a buggy API in the x.y cycle
- months later we'll release x.y
- users will use a buggy API throughout x.y
- we remove the API in x.y+1
- months later we'll release x.y+1
- users will complain about the breakage
- developer will finally roll out a fix

In particular, I don't think there's any good way to encourage/force
developers to turn on developer warnings and we definitely don't want
to have them on for everyone.

Or maybe.. what if we make the developer warnings on by default
whenever hg sees its version string is not a normal release number.
That might move the needle.

-- 
Mathematics is the supreme nostalgia of our time.