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

[Pierre-Yves David]

[apparently this message never made it to the internet]

On 12/02/2015 03:31 PM, Matt Mackall wrote:
> 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.

They are on by default in run-tests.py for 6 months. So anyone who 
updated its test runners since then will have tests failing during the 
grace period.

There is a lot of copy pasted run-tests.py around that do not have the 
config on, but I expect developer to get bitten one or two times before 
switching to the core run-tests.py (or at least update it).

We have chicken and eggs situation here, but I hope that eggs that keep 
breaking will encourage people to get acquire a chicken.

> 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.

That sounds like a good idea (I've them on myself, but it is a manual 
process).
In a similar vein, we could also detect test environment in the ui code 
and turn them on by default for all test run.

-- 
Pierre-Yves David