DevKit updates (#412)

.github/ISSUE_TEMPLATE.md

@@ -14,12 +14,14 @@
 
 ```
 $ composer show --latest 'sonata-project/*'
+# Put the result here.
 ```
 
 #### Symfony packages
 
 ```
 $ composer show --latest 'symfony/*'
+# Put the result here.
 ```
 
 #### PHP version

.travis.yml

@@ -14,7 +14,7 @@ php:
   - nightly
 
 sudo: false
-dist: precise
+dist: trusty
 
 cache:
   pip: true
@@ -53,7 +53,6 @@ matrix:
     - php: '7.1'
       env: SYMFONY_DEPRECATIONS_HELPER=0
     - php: hhvm
-      dist: trusty
   allow_failures:
     - php: nightly
     - php: hhvm

.travis/install_test.sh

@@ -19,6 +19,8 @@ chmod u+x "${HOME}/bin/coveralls"
 # To be removed when these issues are resolved:
 # https://github.com/composer/composer/issues/5355
 # https://github.com/composer/composer/issues/5030
-composer update --prefer-dist --no-interaction --prefer-stable --quiet --ignore-platform-reqs
+if [ "${COMPOSER_FLAGS}" = '--prefer-lowest' ]; then
+    composer update --prefer-dist --no-interaction --prefer-stable --quiet --ignore-platform-reqs
+fi
 
 composer update --prefer-dist --no-interaction --prefer-stable ${COMPOSER_FLAGS}

CONTRIBUTING.md

@@ -113,9 +113,9 @@ Some rules have to be respected about the test:
   * `@codeCoverageIgnore`
   * `@codeCoverageIgnoreStart`
   * `@codeCoverageIgnoreEnd`
-* All test methods should be prefixed by `test`. Example: `public function testItReturnsNull()`.
-* All test method names must be in camel case format.
+* All test methods must be prefixed by `test`. Example: `public function testItReturnsNull()`.
 * As opposed, the `@test` annotation is prohibited.
+* All test method names must be in camel case format.
 * Most of the time, the test class should have the same name as the targeted class, suffixed by `Test`.
 * The `@expectedException*` annotations are prohibited. Use `PHPUnit_Framework_TestCase::setExpectedException()`.
 
@@ -232,8 +232,62 @@ interface BarInterface
 }
 ```
 
-In some cases, you will have the possibility to warn the user that things will change,
-and recommend a new way of doing things. You can do so by triggering the dedicated kind of error, like this:
+##### Deprecation
+
+In some cases, you might have some code parts that might become superseded by others, but could still be used by the end user.
+If the concerned code is not tagged as `internal`, it must be deprecated on the stable branch, then removed.
+
+If an alternate usage solution is possible, you **MUST** provide it in the deprecation message.
+
+The deprecated minor version **MUST NOT** be provided. Use `x` instead. It will be updated when releasing.
+
+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.
+
+You have three ways to deprecate things.
+
+For class definitions, methods (or first level functions) and properties, use the `@deprecated` tag: 
+
+```php
+/**
+ * @deprecated since 42.x, to be removed in 43.0. Use Shiny\New\ClassOfTheMonth instead.
+ */
+final class IAmOldAndUseless
+{
+}
+
+final class StillUsedClass
+{
+    /**
+     * @deprecated since 42.x, to be removed in 43.0.
+     */
+    public $butNotThisProperty;
+
+    /**
+     * @deprecated since 42.x, to be removed in 43.0.
+     */
+    public function iAmBatman()
+    {
+        echo "But this is not Gotham here.";
+    }
+}
+```
+
+If the deprecated thing is a service, you **MUST** specify it on the service definition:
+
+```xml
+<service id="sonata.block.old" class="Sonata\Block\Old">
+    <argument type="service" id="security.token_storage" />
+    <deprecated>The "%service_id%" service is deprecated since 42.x and will be removed in 43.0.</deprecated>
+ </service>
+ ```
+
+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.
 
 ```php
 <?php
@@ -248,26 +302,14 @@ if (/* some condition showing the user is using the legacy way */) {
 }
 ```
 
-Additionally, and when applicable, you must use the `@deprecated` tag on classes or methods you wish to deprecate,
-along with a message directed at the end user (as opposed to other contributors).
-
-
-```php
-/**
- * NEXT_MAJOR: remove this method
- *
- * @deprecated since 3.x, to be removed in 4.0. Use Foo::bar instead.
- */
-public function baz()
-{
-}
-```
+Note that the `trigger_error` usage is not necessary if the `@deprecated` tag is used.
 
-In that case, unit tests might show your deprecation notice. You must mark such tests with the `@group legacy` annotation,
-and if need be, isolate them in a new test method that can simply be removed in the non-BC PR.
+In the case of a deprecation, unit tests might show your deprecation notice.
+You **MUST** mark such tests with the `@group legacy` annotation and if need be,
+isolate them in a new test method that can simply be removed in the non-BC PR.
 
 Be aware that pull requests with BC breaks could be rejected
-or postponed to next major release if BC is not possible.
+or postponed to next major release **only** if BC is not possible.
 
 If you are not sure what should be done, don't hesitate to open an issue about your PR project.