Updated: Comment #12
There has been, in the past, no way to distinguish between functions, classes, methods, etc. that absolutely cannot change within a Drupal major version, and those that are allowed to change, except:
- Functions starting with _ can change
- Private class methods can change
It would be useful to have a concept of a stable, public, API for Drupal. We would allow things that are not part of this API to change at certain times, and require that things that are part of this API not change.
At least broadly, follow http://symfony.com/doc/current/contributing/code/bc.html
This means using the following two tags in core, for both classes/interfaces and individual methods:
@api means 'guaranteed backwards compatibility' - always safe to use the class/method or implement it.
@internal means 'likely to change' - don't use this, or be prepared for upheaval if you do.
Not tagged means we assess the impact vs. disruption of any backwards compatibility breaks, only make them when necessary, and ensure there are clear instructions to update. This means that code that is not tagged is in roughly the same category as 7.x or 8.x beta code now.
Agree on whether @api vs. @internal vs. untagged is a good distinction.
Decide what to do about ArrayPIs (mainly form and render structures, but really anything (route definitions etc.) that get passed to alter hooks.
Initially open issues to tag classes/methods as @internal - since this tag can't be applied to code once 8.0.0 is released.
User interface changes
None. This is a policy, not an API change.
Original report by Crell
In order to make it easier to extend core without breaking APIs, we need to clearly define what our APIs are that we don't break. :-) In practice, there are different levels of "API-ness".
Our traditional approach here has been "a line that begins with 'function' can never change without it being an API break (unless the function begins with _, but then we still don't change it just in case)". That is an inadequate standard.
A common technique is to tag "for reals APIs that we're going to promise won't change" with an @api doc tag. We should do the same. That means deciding how we determine what should get tagged that way.
Standards we should NOT use:
* All public methods (this is needlessly redundant and over-promising)
* All protected methods, for child classes (this is needlessly redundant and over-promising)
* All methods that are part of an interface (again, needlessly redundant)
So, what methods, classes, and interfaces should we document as @api meaning "we promise this won't break unless we have to for security" as opposed to simply part of an interface which means "this is the interface and we're pretty sure it won't break, and we'll try really hard not to break it"?