[Bundles] Improve the wording about mapping best practices

Author: javiereguiluz

best_practices.rst

@@ -194,17 +194,20 @@ you'll need to configure services (or parts of them) manually.
 YAML is the format recommended to configure services because it's friendly to
 newcomers and concise, but Symfony also supports XML and PHP configuration.
 
-Use Annotations to Define the Doctrine Entity Mapping
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+Use Attributes to Define the Doctrine Entity Mapping
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 Doctrine entities are plain PHP objects that you store in some "database".
 Doctrine only knows about your entities through the mapping metadata configured
 for your model classes.
 
-Doctrine supports several metadata formats, but it's recommended to use
-annotations because they are by far the most convenient and agile way of setting
+Doctrine supports several metadata formats, but it's recommended to use PHP
+attributes because they are by far the most convenient and agile way of setting
 up and looking for mapping information.
 
+If your PHP version doesn't support attributes yet, use annotations, which is
+similar but requires installing some extra dependencies in your project.
+
 Controllers
 -----------
 

bundles/best_practices.rst

@@ -123,8 +123,8 @@ Type                                                 Directory
 Commands                                             ``src/Command/``
 Controllers                                          ``src/Controller/``
 Service Container Extensions                         ``src/DependencyInjection/``
-Doctrine ORM entities (when not using annotations)   ``src/Entity/``
-Doctrine ODM documents (when not using annotations)  ``src/Document/``
+Doctrine ORM entities                                ``src/Entity/``
+Doctrine ODM documents                               ``src/Document/``
 Event Listeners                                      ``src/EventListener/``
 Configuration (routes, services, etc.)               ``config/``
 Web Assets (CSS, JS, images)                         ``public/``
@@ -162,6 +162,15 @@ standard Symfony autoloading instead.
 A bundle should also not embed third-party libraries written in JavaScript,
 CSS or any other language.
 
+Doctrine Entities/Documents
+---------------------------
+
+If the bundle includes Doctrine ORM entities and/or ODM documents, it's
+recommended to define their mapping using XML files stored in
+``Resources/config/doctrine/``. This allows to override that mapping using the
+:doc:`standard Symfony mechanism to override bundle parts </bundles/override>`.
+This is not possible when using annotations/attributes to define the mapping.
+
 Tests
 -----