Merge branch '2.8'

book/forms.rst

@@ -1782,6 +1782,11 @@ The ``_token`` field is a hidden field and will be automatically rendered
 if you include the ``form_end()`` function in your template, which ensures
 that all un-rendered fields are output.
 
+.. caution::
+
+    Since the token is stored in the session, a session is started automatically
+    as soon as you render a form with CSRF protection.
+
 The CSRF token can be customized on a form-by-form basis. For example::
 
     use Symfony\Component\OptionsResolver\OptionsResolver;

changelog.rst

@@ -13,6 +13,63 @@ documentation.
     Do you also want to participate in the Symfony Documentation? Take a look
     at the ":doc:`/contributing/documentation/overview`" article.
 
+September, 2015
+---------------
+
+New Documentation
+~~~~~~~~~~~~~~~~~
+
+* `#5555 <https://github.com/symfony/symfony-docs/pull/5555>`_ added result yaml and xml from example code (OskarStark)
+* `#5631 <https://github.com/symfony/symfony-docs/pull/5631>`_ Updated the Quick Tour to the latest changes introduced by Symfony (javiereguiluz)
+* `#5497 <https://github.com/symfony/symfony-docs/pull/5497>`_ Simplified the Quick tour explanation about Symfony Installation (DQNEO)
+
+Fixed Documentation
+~~~~~~~~~~~~~~~~~~~
+
+* `#5629 <https://github.com/symfony/symfony-docs/pull/5629>`_ Fixing web user permission (BenoitLeveque)
+* `#5673 <https://github.com/symfony/symfony-docs/pull/5673>`_ Update http_cache.rst (szyszka90)
+* `#5666 <https://github.com/symfony/symfony-docs/pull/5666>`_ Fix EntityManager namespace (JhonnyL)
+* `#5656 <https://github.com/symfony/symfony-docs/pull/5656>`_ Fix monolog line formatter in logging cookbook example. (vmarquez)
+* `#5507 <https://github.com/symfony/symfony-docs/pull/5507>`_ Path fixed (carlosreig)
+
+Minor Documentation Changes
+~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+* `#5740 <https://github.com/symfony/symfony-docs/pull/5740>`_ Fix typo in PdoSessionHandler Documentation (tobemedia)
+* `#5719 <https://github.com/symfony/symfony-docs/pull/5719>`_ changed repo names to the new ones (fabpot)
+* `#5227 <https://github.com/symfony/symfony-docs/pull/5227>`_ [Cookbook] Fix doc on Generic Form Type Extensions (lemoinem)
+* `#5703 <https://github.com/symfony/symfony-docs/pull/5703>`_ comment old logic (OskarStark)
+* `#5683 <https://github.com/symfony/symfony-docs/pull/5683>`_ Improve the demo-warning. (GuGuss)
+* `#5690 <https://github.com/symfony/symfony-docs/pull/5690>`_ Updated the release process image (javiereguiluz)
+* `#5188 <https://github.com/symfony/symfony-docs/pull/5188>`_ Updated Cookies & Caching section (lukey78)
+* `#5710 <https://github.com/symfony/symfony-docs/pull/5710>`_ Fix grammar mistake in security.rst (zatikbalazs)
+* `#5706 <https://github.com/symfony/symfony-docs/pull/5706>`_ Update assetic.rst (Acinonux)
+* `#5705 <https://github.com/symfony/symfony-docs/pull/5705>`_ Update assetic.rst (Acinonux)
+* `#5685 <https://github.com/symfony/symfony-docs/pull/5685>`_ Fix indentation in some annotations (iamdto)
+* `#5704 <https://github.com/symfony/symfony-docs/pull/5704>`_ Fix typo in translation.rst (zatikbalazs)
+* `#5701 <https://github.com/symfony/symfony-docs/pull/5701>`_ Update testing.rst (hansallis)
+* `#5711 <https://github.com/symfony/symfony-docs/pull/5711>`_ removed service call from controller (sloba88)
+* `#5692 <https://github.com/symfony/symfony-docs/pull/5692>`_ Made a sentence slightly more english (GTheron)
+* `#5715 <https://github.com/symfony/symfony-docs/pull/5715>`_ Add missing code tag (zatikbalazs)
+* `#5720 <https://github.com/symfony/symfony-docs/pull/5720>`_ adding closing tag (InfoTracer)
+* `#5714 <https://github.com/symfony/symfony-docs/pull/5714>`_ Remove unnecessary word from http_cache.rst (zatikbalazs)
+* `#5680 <https://github.com/symfony/symfony-docs/pull/5680>`_ fix grammar mistake (greg0ire)
+* `#5682 <https://github.com/symfony/symfony-docs/pull/5682>`_ Fix grammar and CS (iamdto)
+* `#5652 <https://github.com/symfony/symfony-docs/pull/5652>`_ Do not use dynamic REQUEST_URI from $_SERVER as base url (senkal)
+* `#5654 <https://github.com/symfony/symfony-docs/pull/5654>`_ Doc about new way of running tests (nicolas-grekas)
+* `#5598 <https://github.com/symfony/symfony-docs/pull/5598>`_ [Cookbook][Security] proofread comments in voter article (xabbuh)
+* `#5560 <https://github.com/symfony/symfony-docs/pull/5560>`_ [2.3] [Contributing] [CS] Added missing docblocks in code snippet (phansys)
+* `#5674 <https://github.com/symfony/symfony-docs/pull/5674>`_ Update cookbook entries with best practices (JhonnyL)
+* `#5675 <https://github.com/symfony/symfony-docs/pull/5675>`_ [Contributing] add a link to the testing section (xabbuh)
+* `#5669 <https://github.com/symfony/symfony-docs/pull/5669>`_ Better explanation of implicit exception response status code (hvt)
+* `#5651 <https://github.com/symfony/symfony-docs/pull/5651>`_ [Reference][Constraints] follow best practices in the constraints reference (xabbuh)
+* `#5648 <https://github.com/symfony/symfony-docs/pull/5648>`_ Minor fixes for the QuestionHelper documentation (javiereguiluz)
+* `#5641 <https://github.com/symfony/symfony-docs/pull/5641>`_ Move important information out of versionadded (WouterJ)
+* `#5619 <https://github.com/symfony/symfony-docs/pull/5619>`_ Remove a caution note about StringUtils::equals() which is no longer true (javiereguiluz)
+* `#5571 <https://github.com/symfony/symfony-docs/pull/5571>`_ Some small fixes for upload files article (WouterJ)
+* `#5660 <https://github.com/symfony/symfony-docs/pull/5660>`_ Improved "Community Reviews" page (webmozart)
+
+
 August, 2015
 ------------
 

components/dependency_injection/advanced.rst

@@ -218,3 +218,75 @@ You can change the inner service name if you want to:
             ->addArgument(new Reference('bar.wooz'))
             ->setPublic(false)
             ->setDecoratedService('foo', 'bar.wooz');
+
+Deprecating Services
+--------------------
+
+.. versionadded:: 2.8
+    The ``deprecated`` setting was introduced in Symfony 2.8.
+
+Once you have decided to deprecate the use of a service (because it is outdated
+or you decided not to use and maintain it anymore), you can deprecate its
+definition:
+
+.. configuration-block::
+
+    .. code-block:: yaml
+
+       acme.my_service:
+           class: ...
+           deprecated: The "%service_id%" service is deprecated since 2.8 and will be removed in 3.0.
+
+    .. 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="acme.my_service" class="...">
+                    <deprecated>The "%service_id%" service is deprecated since 2.8 and will be removed in 3.0.</deprecated>
+                </service>
+            </services>
+        </container>
+
+    .. code-block:: php
+
+        $container
+            ->register('acme.my_service', '...')
+            ->setDeprecated(
+                true,
+                'The "%service_id%" service is deprecated since 2.8 and will be removed in 3.0.'
+            )
+        ;
+
+Now, every time a service is created using this deprecated definition, a
+deprecation warning will be triggered, advising you to stop or to change your
+uses of that service.
+
+The message is actually a message template, which will replace occurrences
+of the ``%service_id%`` by the service's id. You **must** have at least one
+occurrence of the ``%service_id%`` placeholder in your template.
+
+.. note::
+
+    The deprecation message is optional. If not set, Symfony will show a default
+    message ``The "%service_id%" service is deprecated. You should stop using it,
+    as it will soon be removed.``.
+
+.. tip::
+
+    It is strongly recommended that you fill the message template, to avoid a
+    message that could be too generic such as the default one. A good message
+    informs when this service was deprecated, and until when it will be
+    maintained (look at the examples above).
+
+For service decorators (see above), if the definition does not modify the
+deprecated status, it will inherit the status from the definition that is
+decorated.
+
+.. caution::
+
+    The ability to "un-deprecate" a service is possible only when declaring the
+    definition in PHP.

contributing/documentation/index.rst

@@ -7,5 +7,9 @@ Contributing Documentation
     overview
     format
     standards
-    translations
     license
+
+.. toctree::
+    :hidden:
+
+    translations

contributing/documentation/overview.rst

@@ -299,11 +299,6 @@ Please be patient. It can take up to several days before your pull request can
 be fully reviewed. After merging the changes, it could take again several hours
 before your changes appear on the symfony.com website.
 
-What If I Want to Translate Some Documentation into my Language?
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-Read the dedicated :doc:`document </contributing/documentation/translations>`.
-
 Why Should I Use the Oldest Maintained Branch Instead of the Master Branch?
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 

contributing/documentation/translations.rst

@@ -1,87 +1,7 @@
 Translations
 ============
 
-The Symfony documentation is written in English and many people are involved
-in the translation process.
+The Symfony documentation is not officially translated, though some community
+groups still maintain some translations. For more information, see `this blog post`_.
 
-.. note::
-
-    Symfony Project officially discourages from starting new translations for the
-    documentation. As a matter of fact, there is `an ongoing discussion`_ in
-    the community about the benefits and drawbacks of community driven translations.
-
-Contributing
-------------
-
-First, become familiar with the :doc:`markup language </contributing/documentation/format>`
-used by the documentation.
-
-Finally, find the *master* repository for the language you want to contribute
-for. Here is the list of the official *master* repositories:
-
-* *English*:  https://github.com/symfony/symfony-docs
-* *French*:   https://github.com/symfony-fr/symfony-docs-fr
-* *Italian*:  https://github.com/garak/symfony-docs-it
-* *Japanese*: https://github.com/symfony-japan/symfony-docs-ja
-* *Portuguese (Brazilian)*:  https://github.com/andreia/symfony-docs-pt-BR
-
-.. note::
-
-    If you want to contribute translations for a new language, read the
-    :ref:`dedicated section <translations-adding-a-new-language>`.
-
-Joining the Translation Team
-----------------------------
-
-If you want to help translating some documents for your language or fix some
-bugs, consider joining us; it's a very easy process:
-
-* *(optional)* Ask which documents you can work on;
-* Fork the *master* repository for your language (click the "Fork" button on
-  the GitHub page);
-* Translate some documents;
-* Ask for a pull request (click on the "Pull Request" from your page on
-  GitHub);
-* The team manager accepts your modifications and merges them into the master
-  repository;
-* The documentation website is updated every other night from the master
-  repository.
-
-.. _translations-adding-a-new-language:
-
-Adding a new Language
----------------------
-
-This section gives some guidelines for starting the translation of the
-Symfony documentation for a new language.
-
-As starting a translation is a lot of work,  try to find motivated people
-willing to help.
-
-When the team is ready, nominate a team manager; they will be responsible for
-the *master* repository.
-
-Create the repository and copy the *English* documents.
-
-The team can now start the translation process.
-
-When the team is confident that the repository is in a consistent and stable
-state (everything is translated, or non-translated documents have been removed
-from the toctrees -- files named ``index.rst`` and ``map.rst.inc``), the team
-manager can ask that the repository is added to the list of official *master*
-repositories by sending an email to Fabien (fabien at symfony.com).
-
-Maintenance
------------
-
-Translation does not end when everything is translated. The documentation is a
-moving target (new documents are added, bugs are fixed, paragraphs are
-reorganized, ...). The translation team need to closely follow the English
-repository and apply changes to the translated documents as soon as possible.
-
-.. caution::
-
-    Non maintained languages are removed from the official list of
-    repositories as obsolete documentation is dangerous.
-
-.. _`an ongoing discussion`: https://github.com/symfony/symfony-docs/issues/4078
+.. _`this blog post`: http://symfony.com/blog/discontinuing-the-symfony-community-translations

contributing/map.rst.inc

@@ -17,7 +17,6 @@
   * :doc:`Overview </contributing/documentation/overview>`
   * :doc:`Format </contributing/documentation/format>`
   * :doc:`Documentation Standards </contributing/documentation/standards>`
-  * :doc:`Translations </contributing/documentation/translations>`
   * :doc:`License </contributing/documentation/license>`
 
 * **Community**