[Contributing] Add more information on deprecations #12075
Conversation
| A feature is marked as deprecated by adding a ``@deprecated`` phpdoc to | ||
| relevant classes, methods, properties, ...:: | ||
|
|
||
| /** | ||
| * @deprecated since vendor-name/package-name 2.8, to be removed in 3.0. Use XXX instead. | ||
| * @deprecated since Symfony 2.8. |
There was a problem hiding this comment.
Why the rewording here?
cc @greg0ire
There was a problem hiding this comment.
I added this after talking with @nicolas-grekas, what's the deal?
There was a problem hiding this comment.
Yes you added the vendor/... thingy which now gets removed, that’s my point
There was a problem hiding this comment.
I know, I was more asking @fancyweb or @nicolas-grekas to explain the sudden change of heart
There was a problem hiding this comment.
I think the misunderstanding is because this is the "Contribute to Symfony" doc ... so it's not a generic-purpose doc and we don't need things like "vendor-name/package-name" because "vendor" is always "Symfony" and the "package-name" is not usually included in the Symfony deprecation messages.
There was a problem hiding this comment.
Regarding the package name, there is not always a way to guess it from a class name, for instance here:
Also, why remove the Use XXX instead. part? If there is a replacement, it should absolutely be mentioned IMO.
There was a problem hiding this comment.
The "use XXX instead" is not removed. This example is just below.
There was a problem hiding this comment.
@greg0ire this link points to a notice, not to a deprecation :)
There was a problem hiding this comment.
Oh right my bad, here is another example:
|
We don’t use symfony/thing anymore but just Symfony. We also don’t write
the “to be removed” part anymore because this is implicit.
|
b9efa28 to
5fabd5d
Compare
| A feature is marked as deprecated by adding a ``@deprecated`` phpdoc to | ||
| relevant classes, methods, properties, ...:: | ||
|
|
||
| /** | ||
| * @deprecated since vendor-name/package-name 2.8, to be removed in 3.0. Use XXX instead. | ||
| * @deprecated since Symfony 2.8. |
There was a problem hiding this comment.
I think the misunderstanding is because this is the "Contribute to Symfony" doc ... so it's not a generic-purpose doc and we don't need things like "vendor-name/package-name" because "vendor" is always "Symfony" and the "package-name" is not usually included in the Symfony deprecation messages.
5fabd5d to
71560da
Compare
|
Thank you @fancyweb. |
…cyweb) This PR was merged into the 3.4 branch. Discussion ---------- [Contributing] Add more information on deprecations The goal is to add information I gathered from @nicolas-grekas and others in reviews about what the core team expect when you deprecate / remove code. I will add a section for "Features" later. Commits ------- 71560da [Contributing] Add more information on deprecations
* 3.4: Add in the DOW crawler documentation code sample to show how to tick checkboxes Adds the most basic informations about loaders [#12075] fix some casing [Contributing] Add more information on deprecations
* 4.3: Add in the DOW crawler documentation code sample to show how to tick checkboxes Adds the most basic informations about loaders [#12075] fix some casing [Contributing] Add more information on deprecations
* 4.4: Add in the DOW crawler documentation code sample to show how to tick checkboxes Adds the most basic informations about loaders [#12075] fix some casing [Contributing] Add more information on deprecations
…ted class (fsoedjede) This PR was merged into the 3.4 branch. Discussion ---------- [Contributing] Fix `trigger_error()` position in deprecated class The code was added in commit: a2c04e7 The change introducing the issue was added in the PR: #12075 <!-- If your pull request fixes a BUG, use the oldest maintained branch that contains the bug (see https://symfony.com/roadmap for the list of maintained branches). If your pull request documents a NEW FEATURE, use the same Symfony branch where the feature was introduced (and `master` for features of unreleased versions). --> Commits ------- 0dc5efc [Contributing] Fix `trigger_error()` position in deprecated class
The goal is to add information I gathered from @nicolas-grekas and others in reviews about what the core team expect when you deprecate / remove code.
I will add a section for "Features" later.