[RFC] Remove the distinction between api and non-api classes #15977
Comments
|
👍 to remove api tags as they are unmaintained and only distinguish between |
|
👍 Not distinguishing makes it more clear and we can still add some classes as internal. |
|
👍 The concept is interesting but it needs maintenance, which we never did. And as pointed bu @stof, we are getting better at keeping BC almost everywhere, so it's not as needed as it once was. |
|
Is it enough to remove the tags in 2.8? Or also since 2.3? |
|
Well, I suggest cleaning it in all branches, to avoid confusion. And then, the doc should be updated to stop talking about this distinction (dropping it is mostly a job for the doc team, as this is where the concept is used) |
|
Doing it in 2.3 sounds good to me. |
|
I bet this will be a huge merging pain, esp. in master. |
|
@Tobion removing it in all branches means we have the merging pain only once, rather than having merge conflicts during the whole maintenance lifetime each time a phpdoc update is propagated to newer branches. |
|
see symfony/symfony-docs#5735 for the docs changes |
|
👍 but if we do that maybe should we add |
|
@dunglas I think that's the whole idea: instead of whitelisting the API, we need to blacklist internal classes. We've done that already for some classes during the 2.8 development cycle and we need to do more of that. |
This PR was merged into the 2.3 branch. Discussion ---------- remove api tags from code | Q | A | ------------- | --- | Bug fix? | no | New feature? | no | BC breaks? | no | Deprecations? | no | Tests pass? | yes | Fixed tickets | #15977 | License | MIT | Doc PR | n/a Commits ------- f1c7c65 remove api tags from code
|
@dunglas normalizers are not an internal API. they are the extension point we provide to users, and so we expect to see implementations of the interface outside the component. |
|
I'm not speaking about the interface but about implementations such as |
|
@dunglas no. It is simply that it was merged in Symfony after the last time we maintained the |
|
and this class is still meant to be used by users of the component, so it is not internal. |
… and API classes (xabbuh) This PR was merged into the 2.3 branch. Discussion ---------- [Contributing][Code] do not distinguish regular classes and API classes | Q | A | ------------- | --- | Doc fix? | no | New docs? | kind of (symfony/symfony#15977, symfony/symfony#15979) | Applies to | all | Fixed tickets | Commits ------- 9794d58 do not distinguish regular classes and API classes
This PR was merged into the 2.3 branch. Discussion ---------- Remove references to API tagging | Q | A | ------------- | --- | Doc fix? | yes | New docs? | no | Applies to | 2.3 | Fixed tickets | n/a Related to symfony/symfony#15977 and symfony/symfony#15979. Commits ------- d816c7f Remove references to API tagging
We introduced
@apiin 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
@apiAFAIK. 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
Regularcolumn 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@apiclasses), defeating the@apidistinction.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 ?
The text was updated successfully, but these errors were encountered: