Merge branch '3.4' into 4.1

* 3.4:
  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

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`.
@@ -426,3 +431,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

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/

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``