Merge branch '4.1'

* 4.1:
  added mentoring and speaker mentoring sections
  Fix translation debug examples
  [Dotenv] Advise using the Composer --dev option
  Fixed some RST syntax issues
  Add note about configuration root node
  Add twig.runtime
  Updating language to remove ORM
  Recommend to install ORM pack instead of Doctrine bundle

Author: javiereguiluz

bundles/configuration.rst

@@ -47,15 +47,9 @@ as integration of other related components:
 Using the Bundle Extension
 --------------------------
 
-The basic idea is that instead of having the user override individual
-parameters, you let the user configure just a few, specifically created,
-options. As the bundle developer, you then parse through that configuration and
-load correct services and parameters inside an "Extension" class.
-
-As an example, imagine you are creating a social bundle, which provides
-integration with Twitter and such. To be able to reuse your bundle, you have to
-make the ``client_id`` and ``client_secret`` variables configurable. Your
-bundle configuration would look like:
+Imagine you are creating a new bundle - AcmeSocialBundle - which provides
+integration with Twitter, etc. To make your bundle easy to use, you want to
+allow users to configure it with some configuration that looks like this:
 
 .. configuration-block::
 
@@ -92,6 +86,17 @@ bundle configuration would look like:
             'client_secret' => 'your_secret',
         ));
 
+The basic idea is that instead of having the user override individual
+parameters, you let the user configure just a few, specifically created,
+options. As the bundle developer, you then parse through that configuration and
+load correct services and parameters inside an "Extension" class.
+
+.. note::
+
+    The root key of your bundle configuration (``acme_social`` in the previous
+    example) is automatically determined from your bundle name (it's the
+    `snake case`_ of the bundle name without the ``Bundle`` suffix ).
+
 .. seealso::
 
     Read more about the extension in :doc:`/bundles/extension`.
@@ -428,3 +433,4 @@ Assuming the XSD file is called ``hello-1.0.xsd``, the schema location will be
 .. _`TwigBundle Configuration`: https://github.com/symfony/symfony/blob/master/src/Symfony/Bundle/TwigBundle/DependencyInjection/Configuration.php
 .. _`XML namespace`: https://en.wikipedia.org/wiki/XML_namespace
 .. _`XML schema`: https://en.wikipedia.org/wiki/XML_schema
+.. _`snake case`: https://en.wikipedia.org/wiki/Snake_case

components/dotenv.rst

@@ -13,7 +13,7 @@ Installation
 
 .. code-block:: terminal
 
-    $ composer require symfony/dotenv
+    $ composer require --dev symfony/dotenv
 
 Alternatively, you can clone the `<https://github.com/symfony/dotenv>`_ repository.
 

contributing/community/index.rst

@@ -7,4 +7,6 @@ Community
     releases
     review-comments
     reviews
+    mentoring
+    speaker-mentoring
     other

contributing/community/mentoring.rst

@@ -0,0 +1,13 @@
+Mentoring
+=========
+
+Reading the :doc:`contributing </contributing/index>` is already a great way
+to get started on becoming a Symfony contributor. However, sometimes
+it might still seem overwhelming - contributing can be complex! For this
+purpose we created a dedicated `Symfony Slack`_ channel called `#mentoring`_
+to connect new contributors to long-time contributors. This is a great way
+to get one-on-one advice on the entire process. These long-time contributors
+do really want to help new contributors - so feel free to ask anything!
+
+.. _`Symfony Slack`: https://symfony.com/slack-invite
+.. _`#mentoring`: https://symfony-devs.slack.com/messages/mentoring

contributing/community/speaker-mentoring.rst

@@ -0,0 +1,44 @@
+Speaker Mentoring
+=================
+
+The Symfony community benefits greatly when as many people as possible
+share their knowledge and experience with others. Every different
+point of view adds to our collective understanding of how to best use
+and evolve the code, design patterns and architecture provided within
+the Symfony community. Because of this, we specifically want to hear
+from long-time contributors and new users, who often come across entirely
+different challenges with a totally fresh new look and perspective.
+
+How to get started
+------------------
+
+Giving a first talk at a conference can seem quite intimidating. But
+don't worry! At one time, every speaker went through the same process.
+And so, we want to make sure that as many people as possible are empowered
+to take this path if they are motivated. We have collected a few resources
+with advice to get started. More importantly, we can connect experienced
+speakers with people who are just taking their first steps in this area:
+
+.. tip::
+
+    A good first step might be to give a talk at a local user group to a
+    smaller crowd that one knows more intimately. A next step could be to
+    give a talk at conference in your first language.
+
+The best way to find people that can review your talk idea or slides is
+the `#speaker-mentoring`_ channel on `Symfony Slack`_. There are many
+seasoned speakers with knowledge in various parts of Symfony that are
+motivated to help you get started on your path towards becoming a
+public speaker. They can even do practice runs via video chat!
+Furthermore, they can also be an ally when it comes to the day of
+giving the talk at a conference!
+
+A great resource with advice on everything related to`public speaking`_
+is a collection of links maintained by VM (Vicky) Brasseur. It covers
+everything from finding a conference call for proposals, how to
+refine a proposal, to how to put together slide decks to practical
+tips for preparation and talk delivery.
+
+.. _`#speaker-mentoring`: https://symfony-devs.slack.com/messages/speaker-mentoring
+.. _`Symfony Slack`: https://symfony.com/slack-invite
+.. _`public speaking`: https://github.com/vmbrasseur/Public_Speaking

doctrine/dbal.rst

@@ -21,11 +21,11 @@ makes it easy to execute queries and perform other database actions.
     Read the official Doctrine `DBAL Documentation`_ to learn all the details
     and capabilities of Doctrine's DBAL library.
 
-First, install the Doctrine bundle:
+First, install the Doctrine ORM pack:
 
 .. code-block:: terminal
 
-    $ composer require doctrine/doctrine-bundle
+    $ composer require symfony/orm-pack
 
 Then configure the ``DATABASE_URL`` environment variable in ``.env``:
 
@@ -36,9 +36,9 @@ Then configure the ``DATABASE_URL`` environment variable in ``.env``:
     # customize this line!
     DATABASE_URL="mysql://db_user:[email protected]:3306/db_name"
 
-Further things can be configured in ``config/packages/doctrine.yaml``. For the full
-DBAL configuration options, or to learn how to configure multiple connections,
-see :ref:`reference-dbal-configuration`.
+Further things can be configured in ``config/packages/doctrine.yaml`` - see
+:ref:`reference-dbal-configuration`. Remove the ``orm`` key in that file
+if you *don't* want to use the Doctrine ORM.
 
 You can then access the Doctrine DBAL connection by autowiring the ``Connection``
 object::

frontend/encore/faq.rst

@@ -3,12 +3,12 @@ FAQ and Common Issues
 
 .. _how-do-i-deploy-my-encore-assets:
 
-How do I deploy my Encore Assets?
+How Do I Deploy My Encore Assets?
 ---------------------------------
 
 There are two important things to remember when deploying your assets.
 
-**1) Compile assets for production**
+**1) Compile Assets for Production**
 
 Optimize your assets for production by running:
 
@@ -19,11 +19,12 @@ Optimize your assets for production by running:
 That will minify your assets and make other performance optimizations. Yay!
 
 But, what server should you run this command on? That depends on how you deploy.
-For example, you could execute this locally (or on a build server), and use rsync
-or something else to transfer the built files to your server. Or, you could put your
-files on your production server first (e.g. via a git pull) and then run this command
-on production (ideally, before traffic hits your code). In this case, you'll need
-to install Node.js on your production server.
+For example, you could execute this locally (or on a build server), and use
+`rsync`_ or something else to transfer the generated files to your production
+server. Or, you could put your files on your production server first (e.g. via
+``git pull``) and then run this command on production (ideally, before traffic
+hits your code). In this case, you'll need to install Node.js on your production
+server.
 
 **2) Only Deploy the Built Assets**
 
@@ -34,13 +35,13 @@ asset files, **unless** you plan on running ``encore production`` on your produc
 machine. Once your assets are built, these are the *only* thing that need to live
 on the production server.
 
-Do I need to Install Node.js on my Production Server?
+Do I Need to Install Node.js on My Production Server?
 -----------------------------------------------------
 
 No, unless you plan to build your production assets on your production server,
-which is not recommended. See `How do I deploy my Encore Assets?`_.
+which is not recommended. See `How Do I Deploy my Encore Assets?`_.
 
-What Files Should I commit to git? And which should I Ignore?
+What Files Should I Commit to git? And which Should I Ignore?
 -------------------------------------------------------------
 
 You should commit all of your files to git, except for the ``node_modules/`` directory
@@ -131,3 +132,5 @@ this via:
 
     // require a non-minified file whenever possible
     require('respond.js/dest/respond.src.js');
+
+.. _`rsync`: https://rsync.samba.org/

reference/dic_tags.rst

@@ -41,6 +41,7 @@ Tag Name                                  Usage
 `translation.dumper`_                     Register a custom service that dumps translation messages
 `twig.extension`_                         Register a custom Twig Extension
 `twig.loader`_                            Register a custom service that loads Twig templates
+`twig.runtime`_                           Register a lazy-loaded Twig Extension
 `validator.constraint_validator`_         Create your own custom validation constraint
 `validator.initializer`_                  Register a service that initializes objects before validation
 ========================================  ========================================================================
@@ -1175,6 +1176,51 @@ also register it manually:
     The ``priority`` value is optional and defaults to ``0``.
     The higher priority loaders are tried first.
 
+.. _reference-dic-tags-twig-runtime:
+
+twig.runtime
+------------
+
+**Purpose**: To register a custom Lazy-Loaded Twig Extension
+
+:ref:`Lazy-Loaded Twig Extensions <lazy-loaded-twig-extensions>` are defined as
+regular services but the need to be tagged with ``twig.runtime``. If you're using the
+:ref:`default services.yaml configuration <service-container-services-load-example>`,
+the service is auto-registered and auto-tagged. But, you can also register it manually:
+
+.. configuration-block::
+
+    .. code-block:: yaml
+
+        services:
+            App\Twig\AppExtension:
+                tags: [twig.runtime]
+
+    .. code-block:: xml
+
+        <?xml version="1.0" encoding="UTF-8" ?>
+        <container xmlns="http://symfony.com/schema/dic/services"
+            xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+            xsi:schemaLocation="http://symfony.com/schema/dic/services
+                http://symfony.com/schema/dic/services/services-1.0.xsd">
+
+            <services>
+                <service id="App\Twig\AppExtension">
+                    <tag name="twig.runtime" />
+                </service>
+            </services>
+        </container>
+
+    .. code-block:: php
+
+        use App\Twig\AppExtension;
+        use App\Twig\AnotherExtension;
+
+        $container
+            ->register(AppExtension::class)
+            ->addTag('twig.runtime')
+        ;
+
 validator.constraint_validator
 ------------------------------
 

setup/built_in_web_server.rst

@@ -64,7 +64,7 @@ can change the socket passing an IP address and a port as a command-line argumen
 
         $ php bin/console server:status 192.168.0.1:8080
 
-    The first command shows if your Symfony application will be server through
+    The first command shows if your Symfony application will be served through
     ``localhost:8000``, the second one does the same for ``192.168.0.1:8080``.
 
 .. tip::

translation/debug.rst

@@ -143,7 +143,7 @@ for the ``fr`` locale and run the command, you will get:
     ---------  ------------------  ----------------------  -------------------------------
      State      Id                  Message Preview (fr)    Fallback Message Preview (en)
     ---------  ------------------  ----------------------  -------------------------------
-     missing    Symfony is great    J'aime Symfony          Symfony is great
+     missing    Symfony is great    Symfony is great        Symfony is great
     ---------  ------------------  ----------------------  -------------------------------
 
 The state indicates the message is missing because it is not translated in
@@ -162,7 +162,7 @@ translation file in the ``fr`` locale and run the command, you will get:
     ----------  ------------------  ----------------------  -------------------------------
      State      Id                  Message Preview (fr)    Fallback Message Preview (en)
     ----------  ------------------  ----------------------  -------------------------------
-     fallback    Symfony is great    J'aime Symfony          Symfony is great
+     fallback    Symfony is great    Symfony is great        Symfony is great
     ----------  ------------------  ----------------------  -------------------------------
 
 You can see that the translations of the message are identical in the ``fr``