diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 833d91d1..4cf35821 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -272,15 +272,17 @@ The deprecated minor version **MUST NOT** be provided. Use `x` instead. It will Any deprecation **MUST** be documented in the corresponding `UPGRADE-[0-9].x.md`. The documentation **MUST** be filled inside the top **unreleased** section with a sub title. -The `NEXT_MAJOR` tag SHOULD not be used for deprecation. -The `@deprecated` and `E_USER_DEPRECATED` key will be searched for before releasing the next major version. +The `NEXT_MAJOR` tag SHOULD also be used for deprecations, it will be searched for before releasing the next major version. You have three ways to deprecate things. -For class definitions, methods (or first level functions) and properties, use the `@deprecated` tag: +For class definitions and properties, use the `@deprecated` tag. +For methods, use the `@deprecated` tag and trigger a deprecation with `@trigger_error('...', E_USER_DEPRECATED)`: ```php /** + * NEXT_MAJOR: Remove this class. + * * @deprecated since sonata-project/foo-lib 42.x, to be removed in 43.0. Use Shiny\New\ClassOfTheMonth instead. */ final class IAmOldAndUseless @@ -290,15 +292,24 @@ final class IAmOldAndUseless final class StillUsedClass { /** + * NEXT_MAJOR: Remove this property. + * * @deprecated since sonata-project/foo-lib 42.x, to be removed in 43.0. */ public $butNotThisProperty; /** + * NEXT_MAJOR: Remove this method. + * * @deprecated since sonata-project/foo-lib 42.x, to be removed in 43.0. */ public function iAmBatman() { + @trigger_error(sprintf( + 'Method %s() is deprecated since sonata-project/foo-lib 42.x and will be removed in version 43.0.', + __METHOD__ + ), E_USER_DEPRECATED); + echo "But this is not Gotham here."; } } @@ -307,6 +318,7 @@ final class StillUsedClass If the deprecated thing is a service, you **MUST** specify it on the service definition: ```xml + The "%service_id%" service is deprecated since sonata-project/bar-bundle 42.x and will be removed in 43.0. @@ -315,14 +327,15 @@ If the deprecated thing is a service, you **MUST** specify it on the service def More info: http://symfony.com/blog/new-in-symfony-2-8-deprecated-service-definitions -For everything else, not managed by the `@deprecated` tag, you **MUST** trigger a deprecation message. +For everything else, not managed by the `@deprecated` tag, +you **MUST** still trigger a deprecation message (and add a `NEXT_MAJOR` comment). ```php