[Workflow] config doc

Author: noniagriconomie

.github/CODEOWNERS

@@ -0,0 +1,27 @@
+# Console
+/console* @chalasr
+/components/console* @chalasr
+
+# Form
+/forms.rst @xabbuh
+/components/form* @xabbuh
+/reference/forms* @xabbuh
+
+# PropertyInfo
+/components/property_info* @dunglas
+
+# Security
+/security* @chalasr
+/components/security* @chalasr
+
+# Validator
+/validation/*
+/components/validator* @xabbuh
+/reference/constraints* @xabbuh
+
+# Workflow
+/workflow* @lyrixx
+/components/workflow* @lyrixx
+
+# Yaml
+/components/yaml* @xabbuh

_build/_themes/_exts/symfonycom/sphinx/lexer.py

@@ -10,7 +10,7 @@ class TerminalLexer(RegexLexer):
     tokens = {
         'root': [
             ('^\$', Generic.Prompt, 'bash-prompt'),
-            ('^[^\n>]+>', Generic.Prompt, 'dos-prompt'),
+            ('^>', Generic.Prompt, 'dos-prompt'),
             ('^#.+$', Comment.Single),
             ('^.+$', Generic.Output),
         ],

_build/maintainer_guide.rst

@@ -93,7 +93,7 @@ interface. Then:
 Merging Process
 ~~~~~~~~~~~~~~~
 
-At first it's common to make mistakes and merge things badly. Don't worry. This
+At first, it's common to make mistakes and merge things badly. Don't worry. This
 has happened to all of us and we've always been able to recover from any mistake.
 
 Step 1: Select the right branch to merge
@@ -120,8 +120,8 @@ Step 2: Merge the pull request
 Never use GitHub's web interface (or desktop clients) to merge PRs or to solve
 merge conflicts. Always use the ``gh`` tool for anything related to merges.
 
-We require 2 approval votes from team members before merging a PR, except if
-it's a typo, a small change or an obvious error.
+We require two approval votes from team members before merging a PR, except if
+it's a typo, a small change or clearly an error.
 
 If a PR contains lots of commits, there's no need to ask the contributor to
 squash them. The ``gh`` tool does that automatically. The only exceptions are

_build/redirection_map

@@ -417,3 +417,15 @@
 /workflow/state-machines /workflow/introduction
 /workflow/usage /workflow
 /introduction/from_flat_php_to_symfony2 /introduction/from_flat_php_to_symfony
+/configuration/environment_variables /configuration/env_var_processors
+/configuration/configuration_organization /configuration
+/configuration/environments /configuration
+/configuration/configuration_organization /configuration
+/email/dev_environment /mailer
+/email/spool /mailer
+/email/testing /mailer
+/contributing/community/other /contributing/community
+/profiler/storage /profiler
+/setup/composer /setup
+/security/security_checker /setup
+/service_container/parameters /configuration

_images/components/workflow/pull_request.png

@@ -0,0 +1,58 @@
+How to Create Symfony Diagrams
+==============================
+
+Creating the Diagram
+--------------------
+
+* Use [Dia][1] as the diagramming application;
+* Use [PT Sans Narrow][2] as the only font in all diagrams (if possible, use
+  only the "normal" weight for all contents);
+* Use 36pt as the base font size;
+* Use 0.10 cm width for lines and shape borders;
+* Use the following color palette:
+  * Text, lines and shape borders: black (#000000)
+  * Shape backgrounds:
+    * Grays: dark (#4d4d4d), medium (#b3b3b3), light (#f2f2f2)
+    * Blue: #b2d4eb
+    * Red: #ecbec0
+    * Green: #b2dec7
+    * Orange: #fddfbb
+
+In case of doubt, check the existing diagrams or ask to the
+[Symfony Documentation Team][3].
+
+Saving and Exporting the Diagram
+--------------------------------
+
+* Save the original diagram in `*.dia` format in `_images/sources/<folder-name>`;
+* Export the diagram to SVG format and save it in `_images/<folder-name>`.
+
+Including the Diagram in the Symfony Docs
+-----------------------------------------
+
+Use the following snippet to embed the diagram in the docs:
+
+```
+.. raw:: html
+
+    <object data="../_images/<folder-name>/<diagram-file-name>.svg" type="image/svg+xml"></object>
+```
+
+Reasoning
+---------
+
+* Dia was chosen because it's one of the few applications which are free, open
+  source and compatible with Linux, macOS and Windows.
+* Font, colors and line widths were chosen to be similar to the diagrams used
+  in the best tech books.
+
+Troubleshooting
+---------------
+
+* On some macOS systems, Dia cannot be executed as a regular application and
+  you must run the following console command instead:
+  `export DISPLAY=:0 && /Applications/Dia.app/Contents/Resources/bin/dia`
+
+[1]: http://dia-installer.de/
+[2]: https://fonts.google.com/specimen/PT+Sans+Narrow
+[3]: https://symfony.com/doc/current/contributing/code/core_team.html

_images/components/workflow/pull_request_puml_styled.png

@@ -109,8 +109,8 @@ distributed among developers, with a slight preference towards YAML.
 Both formats have the same performance, so this is ultimately a matter of
 personal taste.
 
-We recommend YAML because it's friendly to newcomers and concise. You can
-use any of the other formats if you prefer another format.
+We recommend YAML because it's friendly to newcomers and concise, but you can
+use whatever format you like.
 
 Using a Persistence Layer
 -------------------------
@@ -235,7 +235,7 @@ the following command to install the Doctrine fixtures bundle:
 
 .. code-block:: terminal
 
-    $ composer require doctrine/doctrine-fixtures-bundle
+    $ composer require --dev doctrine/doctrine-fixtures-bundle
 
 Then, this bundle is enabled automatically, but only for the ``dev`` and
 ``test`` environments::

_images/form/form-custom-type-postal-address-fragment-names.svg

@@ -16,9 +16,8 @@ application behavior.
 .. best-practice::
 
     Define the infrastructure-related configuration options as
-    :doc:`environment variables </configuration/environment_variables>`. During
-    development, use the ``.env`` and ``.env.local`` files at the root of your
-    project to set these.
+    :ref:`environment variables <config-env-vars>`. During development, use the
+    ``.env`` and ``.env.local`` files at the root of your project to set these.
 
 By default, Symfony adds these types of options to the ``.env`` file when
 installing new dependencies in the app:
@@ -84,7 +83,7 @@ layer of configuration that's not needed because you don't need or want these
 configuration values to change on each server.
 
 The configuration options defined in the ``services.yaml`` may vary from one
-:doc:`environment </configuration/environments>` to another. That's why Symfony
+:ref:`environment <configuration-environments>` to another. That's why Symfony
 supports defining ``config/services_dev.yaml`` and ``config/services_prod.yaml``
 files so that you can override specific values for each environment.
 
@@ -138,8 +137,8 @@ Constants can be used for example in your Twig templates thanks to the
         Displaying the {{ constant('NUMBER_OF_ITEMS', post) }} most recent results.
     </p>
 
-And Doctrine entities and repositories can now easily access these values,
-whereas they cannot access the container parameters::
+And Doctrine entities and repositories can access these values too, whereas they
+cannot access the container parameters::
 
     namespace App\Repository;
 
@@ -155,7 +154,7 @@ whereas they cannot access the container parameters::
     }
 
 The only notable disadvantage of using constants for this kind of configuration
-values is that you cannot redefine them easily in your tests.
+values is that it's complicated to redefine their values in your tests.
 
 Parameter Naming
 ----------------

_images/form/form-custom-type-postal-address.svg

@@ -89,10 +89,10 @@ The ``@Template`` annotation is useful, but also involves some magic. We
 don't think its benefit is worth the magic, and so recommend against using
 it.
 
-Most of the time, ``@Template`` is used without any parameters, which makes
-it more difficult to know which template is being rendered. It also makes
-it less obvious to beginners that a controller should always return a Response
-object (unless you're using a view layer).
+Most of the time, ``@Template`` is used without any parameters, which makes it
+more difficult to know which template is being rendered. It also hides the fact
+that a controller should always return a Response object (unless you're using a
+view layer).
 
 What does the Controller look like
 ----------------------------------

_images/sources/README.md

@@ -25,7 +25,7 @@ that fit the philosophy of the framework as envisioned by its original creator
 
 .. note::
 
-    **Best practice** is a noun that means *"a well defined procedure that is
+    **Best practice** is a noun that means *"a well-defined procedure that is
     known to produce near-optimum results"*. And that's exactly what this
     guide aims to provide. Even if you don't agree with every recommendation,
     we believe these will help you build great applications with less complexity.

_images/sources/form/form-custom-type-postal-address-fragment-names.dia

@@ -18,10 +18,10 @@ primarily under the ``firewalls`` key.
     API only), we recommend having only *one* firewall entry with the ``anonymous``
     key enabled.
 
-Most applications only have one authentication system and one set of users.
-For this reason, you only need *one* firewall entry. There are exceptions
-of course, especially if you have separated web and API sections on your
-site. But the point is to keep things simple.
+Most applications only have one authentication system and one set of users. For
+this reason, you only need *one* firewall entry. If you have separated web and
+API sections on your site, you will need more firewall entries. But the point is
+to keep things simple.
 
 Additionally, you should use the ``anonymous`` key under your firewall. If
 you need to require users to be logged in for different sections of your

_images/sources/form/form-custom-type-postal-address.dia

@@ -119,4 +119,4 @@ be used as a Twig extension.
 Next: :doc:`/best_practices/forms`
 
 .. _`Twig`: https://twig.symfony.com/
-.. _`Parsedown`: http://parsedown.org/
+.. _`Parsedown`: https://parsedown.org/

best_practices/business-logic.rst

@@ -106,8 +106,8 @@ The built-in functional testing client is great, but it can't be used to
 test any JavaScript behavior on your pages. If you need to test this, consider
 using the `Mink`_ library from within PHPUnit.
 
-Of course, if you have a heavy JavaScript front-end, you should consider using
-pure JavaScript-based testing tools.
+If you have a heavy JavaScript frontend, you should consider using pure
+JavaScript-based testing tools.
 
 Learn More about Functional Tests
 ---------------------------------

best_practices/configuration.rst

@@ -18,7 +18,7 @@ SecurityBundle, DebugBundle, etc.) They are also used to add new features in
 your application via `third-party bundles`_.
 
 Bundles used in your applications must be enabled per
-:doc:`environment </configuration/environments>` in the ``config/bundles.php``
+:ref:`environment <configuration-environments>` in the ``config/bundles.php``
 file::
 
     // config/bundles.php

best_practices/controllers.rst

@@ -197,9 +197,9 @@ of Symfony and the latest beta release:
         include:
               # Minimum supported dependencies with the latest and oldest PHP version
             - php: 7.2
-              env: COMPOSER_FLAGS="--prefer-stable --prefer-lowest" SYMFONY_DEPRECATIONS_HELPER="weak_vendors"
+              env: COMPOSER_FLAGS="--prefer-stable --prefer-lowest" SYMFONY_DEPRECATIONS_HELPER="max[self]=0"
             - php: 7.0
-              env: COMPOSER_FLAGS="--prefer-stable --prefer-lowest" SYMFONY_DEPRECATIONS_HELPER="weak_vendors"
+              env: COMPOSER_FLAGS="--prefer-stable --prefer-lowest" SYMFONY_DEPRECATIONS_HELPER="max[self]=0"
 
               # Test the latest stable release
             - php: 7.0
@@ -306,26 +306,15 @@ following standardized instructions in your ``README.md`` file.
         ### Step 2: Enable the Bundle
 
         Then, enable the bundle by adding it to the list of registered bundles
-        in the `app/AppKernel.php` file of your project:
+        in the `config/bundles.php` file of your project:
 
         ```php
-        // app/AppKernel.php
-
-        // ...
-        class AppKernel extends Kernel
-        {
-            public function registerBundles()
-            {
-                $bundles = [
-                    // ...
-                    new <vendor>\<bundle-name>\<bundle-long-name>(),
-                ];
-
-                // ...
-            }
+        // config/bundles.php
 
+        return [
             // ...
-        }
+            <vendor>\<bundle-name>\<bundle-long-name>::class => ['all' => true],
+        ];
         ```
 
     .. code-block:: rst
@@ -362,26 +351,13 @@ following standardized instructions in your ``README.md`` file.
         ~~~~~~~~~~~~~~~~~~~~~~~~~
 
         Then, enable the bundle by adding it to the list of registered bundles
-        in the ``app/AppKernel.php`` file of your project::
-
-            // app/AppKernel.php
-
-            // ...
-            class AppKernel extends Kernel
-            {
-                public function registerBundles()
-                {
-                    $bundles = [
-                        // ...
-
-                        new <vendor>\<bundle-name>\<bundle-long-name>(),
-                    ];
-
-                    // ...
-                }
+        in the ``config/bundles.php`` file of your project::
 
+            // config/bundles.php
+            return [
                 // ...
-            }
+                <vendor>\<bundle-name>\<bundle-long-name>::class => ['all' => true],
+            ];
 
         .. _`installation chapter`: https://getcomposer.org/doc/00-intro.md
 

best_practices/introduction.rst

@@ -381,7 +381,7 @@ Providing an XML Schema
 
 XML has a very useful feature called `XML schema`_. This allows you to
 describe all possible elements and attributes and their values in an XML Schema
-Definition (an xsd file). This XSD file is used by IDEs for auto completion and
+Definition (an XSD file). This XSD file is used by IDEs for auto completion and
 it is used by the Config component to validate the elements.
 
 In order to use the schema, the XML configuration file must provide an

best_practices/security.rst

@@ -4,7 +4,7 @@
 How to Use Bundle Inheritance to Override Parts of a Bundle
 ===========================================================
 
-.. caution::
+.. deprecated:: 3.4
 
     Bundle inheritance was removed in Symfony 4.0, but you can
     :doc:`override any part of a bundle </bundles/override>` without

best_practices/templates.rst

@@ -178,6 +178,6 @@ For this reason, you can override any bundle translation file from the main
 
 For example, to override the translations defined in the
 ``Resources/translations/FOSUserBundle.es.yml`` file of the FOSUserBundle,
-create a``<your-project>/translations/FOSUserBundle.es.yml`` file.
+create a ``<your-project>/translations/FOSUserBundle.es.yml`` file.
 
 .. _`the Doctrine documentation`: http://docs.doctrine-project.org/projects/doctrine-orm/en/latest/reference/inheritance-mapping.html#overrides