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

[Laurent Charignon]

> On Dec 2, 2015, at 1:20 PM, Pierre-Yves David <pierre-yves.david at ens-lyon.org> wrote:
> 
> 
> 
> On 12/02/2015 01:18 PM, 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.
>> 
>> What do people think? If there’s agreement, I’ll update the MercurialApi page to reflect the (slight) shift in policy. Note that formally we’re still allowed to change anything we want, it just establishes a framework by which we can give people some wiggle room (which marmoute points out is becoming more important as we get more users with extensions we can’t see.)
> 
> I'm +1 for this (not a surprise this message is a result of a discussion with Augie and I)

+1, seems totally reasonable. What do you mean by "extensions we can't see"?

> 
> -- 
> Pierre-Yves David
> _______________________________________________
> Mercurial-devel mailing list
> Mercurial-devel at selenic.com
> https://selenic.com/mailman/listinfo/mercurial-devel