Skip to content

Latest commit

 

History

History
50 lines (37 loc) · 2.15 KB

declarations-lifecycle.md

File metadata and controls

50 lines (37 loc) · 2.15 KB
Raw

Declarations lifecycle

Stability stages

This project provides different type of declarations:

  • Experimental declarations that can be updated or removed freely from the API, even by introducing incompatible changes. These declarations are marked with an experimental annotation requiring an explicit opt-in.
  • Stable declarations that can be used safely, even in most conservative scenarios, and that follow strictly our versioning strategy.
  • Deprecated declarations that is not recommended to use and that will be removed in the next major release from the API. These declarations are marked with the Deprecated annotation from Kotlin.

Evolution principles

Experimental declarations

A new declaration should be introduced in experimental stage for collecting user feedbacks. This change can be included in a patch release.

An experimental declaration shouldn't be promoted to stable if its implementation uses another experimental declaration.

An experimental declaration can be promoted to stable by removing the experimental annotation marking it that requires an explicit opt-in. This change can be included in a minor release.

Stable declarations

A stable declaration introduced should be removed by:

  • Deprecating it with a warning level in a minor release.
  • Deprecating it with an error level in a minor release.
  • Deprecating it with a hidden level in a minor release.
  • Removing it in a major release.