Rewording and use headings

README.rst

@@ -16,7 +16,7 @@ Contributing
 ------------
 
 For more information about contributing a recipe, read the `documentation`_ on
-the main repository.
+the main repository and the Best Practices below.
 
 Unlike for official recipes, the pull requests for new contrib recipes are
 managed by the community. Pull requests are reviewed by the Symfony Bot and
@@ -31,24 +31,44 @@ automatically merged when the following conditions are met (in that order):
 
 * The pull request author or the reviewer is a Symfony Core Merger.
 
-.. _`Symfony Flex`: https://github.com/symfony/flex
-.. _`Symfony recipes`: https://github.com/symfony/recipes
-.. _`documentation`: https://github.com/symfony/recipes
-
-Best practices
+Best Practices
 --------------
 
-1. A recipe for a bundle should not contain all the default config. A good
-recipe only contains suggestion config for an application. That is config that needs
-to be configured but no real default value exists.
+Default Bundle Config
+=====================
 
-2. No recipe should modify other bundle's configuration. The only exception is when
-a recipe append to a collection.
+A recipe for a bundle should not contain all the configuration the bundle has to
+offer. A good recipe only contains a suggestion config for an application. That
+is config that needs to be configured but no real default value exists.
 
-3. No config should be "copied from package". That makes the recipes impossible
-to maintain and to assure their quality.
+Example: The "items per page" in a paginator bundle or API credentials for an API
+client bundle.
 
-4. Most Symfony bundles do not need a recipe. A bundle without config or routes
-will be installed by Flex with no recipe required.
+If environment variables are used, they must be provided to the bundle's config.
 
-5. If environment variables are used, they must be provided to the bundle's config.
+A bundle without config or routes do not need a recipe. Flex is smart enough to
+install that bundle anyways.
+
+Modify Other Bundle's config
+============================
+
+The general rule is that no recipe should modify other bundle's configuration. There
+is however one exception. A recipe is allowed to append to a "config collection".
+
+Example: Add a new connection to DoctrineBundle or add a new cache adapter to Symfony
+Framework bundle.
+
+Maintainability
+===============
+
+The recipes contrib repository should contain the recipes for packages. Using
+"`copy-from-package` Configurator" for routes and config is not allowed. That would
+make the recipes impossible to maintain and to assure their quality.
+
+Recipes is also not a replacement for `composer create-project`. That means it is
+not intended to be used as "bootstrap full application" and copy a lot of PHP code,
+front-end assets etc. Recipes are for quick installation of packages.
+
+.. _`Symfony Flex`: https://github.com/symfony/flex
+.. _`Symfony recipes`: https://github.com/symfony/recipes
+.. _`documentation`: https://github.com/symfony/recipes