Lifecycle annotations

[jariji]

https://lifecycle.r-lib.org/articles/stages.html

Whenever a function is released, a problem is often spotted soon afterwards. I propose lifecycle annotations to allow breaking changes to released "experimental" functions.

[bkamins]

This is a good proposal. We did something of this kind for metadata (now we could formalize it) + e.g. new functions introduced in #3258 could be annotated in the same way.

I wonder if we could also consider not only whole functions but also added arguments to existing functions in the same way (I would do it).

@nalimilan - what do you think? If we agree here I would make an appropriate PR explaining our policy.

[nalimilan]

Why not. But I think we should use this only when really necessary, or the result will just be that our new APIs cannot be relied upon. Users want their code to continue to work in future releases, and the fact that they have been warned that a function may break doesn't make it less painful to update the code when breakage happens. As the doc says:

Breaking a popular function, even if clearly labelled as experimental, is likely to cause widespread pain so we’ll generally try to avoid it.

[bkamins]

see #3262

[jariji]

What do you think about putting these icons on new functions?

"new APIs cannot be relied upon" doesn't seem that bad to me, relative to "untried APIs locked in forever".

[bkamins]

Let us discuss case by case when we add new functions if this is needed. Although we allow this "experimental" status, as discussed in the explanation, we do not want to do it lightly. Rather I would prefer to put such (or similar) label only in places where we feel we are not 100% sure we are having a right design.