How to add a deprecation note about Symfony features

gistfile1.md

In order to generate and log a warning message about a deprecated Symfony feature, use the trigger_error() function as follows:

trigger_error('The enctype method of the form helper was removed. You should use the new method start instead.', E_USER_DEPRECATED);

Please, be as explicit as possible in the deprecation message and always explain the alternative way to use that feature, property, method or class.

@javiereguiluz Could you please add a link of an example in the Symfony code please?

\Symfony\Component\HttpKernel\Tests\Logger has several:

    /**
     * @deprecated
     */
    public function crit($message, array $context = array())
    {
        trigger_error('Use critical() which is PSR-3 compatible', E_USER_DEPRECATED);

        $this->log('critical', $message, $context);
    }

@CalinBolea noticed that we also have a part about deprecations in the contribution docs: http://symfony.com/doc/current/contributing/code/conventions.html#deprecations

Also the conventions about patches: http://symfony.com/doc/current/contributing/code/patches.html