deprecation policy and framework

[jayvdb]

The policy, and the technical framework which supports it, need to be documented and accepted, before 1.0.

They are closely linked and should really be a unified cEP, as the policy imposes requirements on the implementation.

The most critical task is defining where we are now, at 0.8/9. Are we currently trying to provide a dependable API, or is it still in flux until 1.0?

However, the most important step is demarcating what is public vs private. If that is not clear, there may be parts of the code base that need to be declared non-public, which means the API is still in flux.

A common policy that most people agree with is that _ prefix means that the object is explicitly not covered by a deprecation policy. A client that invokes a _ prefixed object has no contract to rely on.

Is everything else a part of the public API? If not, do we have a clear definition of what is in the public API?

[jayvdb]

@sils, the policy aspect of this, wrt 0.9->1.0, needs some direction from you. I can formalise it, if you can steer me as to how drastically we can break:

1. The API
2. The result of bears.

I get the feeling that the API is all mostly private at the moment, except a few entry points. Can we identify which entry points clients are using, then the rest is fair game.

IMO clients expect the algorithms for bears to become better, especially when an underlying linter improves. However, they do like to be advised of such changes in a meaningful way , and in my experience they get quite annoyed if a previously disabled rules suddenly being enabled by default as an ERROR if the problem is not a (fair-dinkum) crash-boom-bang ERROR. It is not fun to be in the position of either having to churn large volumes of code, or disable a linter.

And in the case of coala, with all linting rolled into one, a client may need to upgrade for important bear improvement for one language, but need to pin an old version of the bear for different language.

[sils]

I'd probably do at least a 0.10 before doing a 1.0, because we're a 0. tecnically we can break whatevr we want although we should try to keep backwards compatability as good as possible.

[jayvdb]

Can we add a golden rule that coala-utils must be 100 percent backwards compatible, even in 0.x, except major releases, and with a proper deprecation announcement policy?
That will make it a more reliable package for other people to adopt and contribute to.
It will also give us a test bed for building proper deprecators, and validation of deprecation. If so, I can move much of pywikibot.tools into coala-utils, which includes an existing deprecation framework.

[sils]

we can make coala-utils 1.0, then we have to obey to that. Sure.

[gitmate-bot]

This issue seems stale!

@jayvdb please reassign yourself if you're still working on this.

(Powered by GitMate.io)