Description
We introduced @api
in the early days of Symfony to distinguish the public API, safe to be used thanks to BC, and less safe APIs.
However, none of the APIs introduced after Symfony 2.3 has been tagged as @api
AFAIK. And on the other hand, we became much better at writing BC layers to maintain compatibility until the next major version.
Our BC policy is also lying about its goal: what it describes in the Regular
column is a policy which does not provide BC (only partial BC). And in practice, we are much stricter in our code than what is described in this document (i.e. we provide BC for all classes, not only @api
classes), defeating the @api
distinction.
IMO, the real distinction we should have is between normal APIs (where BC is provided) and internal APIs (tagged as @internal
), which should not be used by people using Symfony (if they call an internal method themselves, they are on their own regarding upgrades).
Note that we already have the concept of internal APIs in Symfony (for instance callback functions needing to be public for PHP 5.3 compat, and turned into private ones in 3.0).
What do you think @symfony/deciders ?