diff --git a/book/security.rst b/book/security.rst index 144e0cfd289..7fc60e42cea 100644 --- a/book/security.rst +++ b/book/security.rst @@ -1782,6 +1782,8 @@ the default for the firewall as a whole). For more information about user provider and firewall configuration, see the :doc:`/reference/configuration/security`. +.. _book-security-roles: + Roles ----- diff --git a/components/dependency_injection/parameters.rst b/components/dependency_injection/parameters.rst index 86cf5a489eb..9b47e5141b9 100644 --- a/components/dependency_injection/parameters.rst +++ b/components/dependency_injection/parameters.rst @@ -336,76 +336,3 @@ To disable this behavior, use the ``string`` type: This is not available for YAML and PHP, because they already have built-in support for the PHP keywords. - -Syntax for Referencing Services -------------------------------- - -You can of course also reference services, which looks a bit different in -each format. You can configure the behavior if the referenced service does -not exist. By default, an exception is thrown when a non-existent service -is referenced. - -YAML -~~~~ - -Start the string with ``@`` or ``@?`` to reference a service in YAML. - -* ``@mailer`` references the ``mailer`` service. If the service does not - exist, an exception will be thrown; -* ``@?mailer`` references the ``mailer`` service. If the service does not - exist, it will be ignored; - -.. code-block:: yaml - - parameters: - # if 'my_mailer' service isn't defined, an exception will be raised - foo: @my_mailer - - # if 'my_logger' service isn't defined, 'bar' will be null - bar: @?my_logger - -.. tip:: - - Use ``@@`` to escape the ``@`` symbol in YAML. ``@@mailer`` will be - converted into the string ``"@mailer"`` instead of referencing the - ``mailer`` service. - -XML -~~~ - -In XML, use the ``service`` type. The behavior if the service does not exist -can be specified using the ``on-invalid`` argument. By default, an exception -is thrown. Valid values for ``on-invalid`` are ``null`` (uses ``null`` in place -of the missing service) or ``ignored`` (very similar, except if used on a -method call, the method call is removed). - -.. code-block:: xml - - - - - - - - - -PHP -~~~ - -In PHP, you can use the -:class:`Symfony\\Component\\DependencyInjection\\Reference` class to reference -a service. The invalid behavior is configured using the second constructor -argument and constants from -:class:`Symfony\\Component\\DependencyInjection\\ContainerInterface`. - -.. code-block:: php - - use Symfony\Component\DependencyInjection\Reference; - - // if 'my_mailer' service isn't defined, an exception will be raised - $container->setParameter('foo', new Reference('my_mailer')); - - // if 'my_logger' service isn't defined, 'bar' will be null - $container->setParameter('bar', new Reference('my_logger', - ContainerInterface::NULL_ON_INVALID_REFERENCE - )); diff --git a/components/map.rst.inc b/components/map.rst.inc index fe243a501b3..f9eab711e07 100644 --- a/components/map.rst.inc +++ b/components/map.rst.inc @@ -141,6 +141,7 @@ * :doc:`/components/translation/introduction` * :doc:`/components/translation/usage` + * :doc:`/components/translation/custom_formats` * :doc:`/components/yaml/index` diff --git a/components/translation/custom_formats.rst b/components/translation/custom_formats.rst new file mode 100644 index 00000000000..cf2d899e4d7 --- /dev/null +++ b/components/translation/custom_formats.rst @@ -0,0 +1,114 @@ +.. index:: + single: Translation; Adding Custom Format Support + +Adding Custom Format Support +============================ + +Sometimes, you need to deal with custom formats for translation files. The +Translation component is flexible enough to support this. Just create a +loader (to load translations) and, optionally, a dumper (to dump translations). + +Imagine that you have a custom format where translation messages are defined +using one line for each translation and parentheses to wrap the key and the +message. A translation file would look like this: + +.. code-block:: text + + (welcome)(accueil) + (goodbye)(au revoir) + (hello)(bonjour) + +Creating a Custom Loader +------------------------ + +To define a custom loader that is able to read these kinds of files, you must create a +new class that implements the +:class:`Symfony\\Component\\Translation\\Loader\\LoaderInterface`. The +:method:`Symfony\\Component\\Translation\\Loader\\LoaderInterface::load` +method will get a filename and parse it into an array. Then, it will +create the catalog that will be returned:: + + use Symfony\Component\Translation\MessageCatalogue; + use Symfony\Component\Translation\Loader\LoaderInterface; + + class MyFormatLoader implements LoaderInterface + { + public function load($resource, $locale, $domain = 'messages') + { + $messages = array(); + $lines = file($resource); + + foreach ($lines as $line) { + if (preg_match('/\(([^\)]+)\)\(([^\)]+)\)/', $line, $matches)) { + $messages[$matches[1]] = $matches[2]; + } + } + + $catalogue = new MessageCatalogue($locale); + $catalogue->add($messages, $domain); + + return $catalogue; + } + + } + +Once created, it can be used as any other loader:: + + use Symfony\Component\Translation\Translator; + + $translator = new Translator('fr_FR'); + $translator->addLoader('my_format', new MyFormatLoader()); + + $translator->addResource('my_format', __DIR__.'/translations/messages.txt', 'fr_FR'); + + echo $translator->trans('welcome'); + +It will print *"accueil"*. + +Creating a Custom Dumper +------------------------ + +It is also possible to create a custom dumper for your format, which is +useful when using the extraction commands. To do so, a new class +implementing the +:class:`Symfony\\Component\\Translation\\Dumper\\DumperInterface` +must be created. To write the dump contents into a file, extending the +:class:`Symfony\\Component\\Translation\\Dumper\\FileDumper` class +will save a few lines:: + + use Symfony\Component\Translation\MessageCatalogue; + use Symfony\Component\Translation\Dumper\FileDumper; + + class MyFormatDumper extends FileDumper + { + protected function format(MessageCatalogue $messages, $domain = 'messages') + { + $output = ''; + + foreach ($messages->all($domain) as $source => $target) { + $output .= sprintf("(%s)(%s)\n", $source, $target); + } + + return $output; + } + + protected function getExtension() + { + return 'txt'; + } + } + +The :method:`Symfony\\Component\\Translation\\Dumper\\FileDumper::format` +method creates the output string, that will be used by the +:method:`Symfony\\Component\\Translation\\Dumper\\FileDumper::dump` method +of the FileDumper class to create the file. The dumper can be used like any other +built-in dumper. In the following example, the translation messages defined in the +YAML file are dumped into a text file with the custom format:: + + use Symfony\Component\Translation\Loader\YamlFileLoader; + + $loader = new YamlFileLoader(); + $catalogue = $loader->load(__DIR__ . '/translations/messages.fr_FR.yml' , 'fr_FR'); + + $dumper = new MyFormatDumper(); + $dumper->dump($catalogue, array('path' => __DIR__.'/dumps')); diff --git a/components/translation/index.rst b/components/translation/index.rst index 3f87cbc1425..c50e43f2be7 100644 --- a/components/translation/index.rst +++ b/components/translation/index.rst @@ -6,3 +6,4 @@ Translation introduction usage + custom_formats diff --git a/components/translation/introduction.rst b/components/translation/introduction.rst index 60cf79e5785..8a74f37e120 100644 --- a/components/translation/introduction.rst +++ b/components/translation/introduction.rst @@ -95,6 +95,9 @@ Loader too. The default loaders are: All file loaders require the :doc:`Config component `. +You can also :doc:`create your own Loader `, +in case the format is not already supported by one of the default loaders. + At first, you should add one or more loaders to the ``Translator``:: // ... diff --git a/contributing/documentation/format.rst b/contributing/documentation/format.rst index d00cdfa4592..4f464e85001 100644 --- a/contributing/documentation/format.rst +++ b/contributing/documentation/format.rst @@ -1,17 +1,19 @@ Documentation Format ==================== -The Symfony documentation uses `reStructuredText`_ as its markup language and -`Sphinx`_ for building the output (HTML, PDF, ...). +The Symfony documentation uses reStructuredText_ as its markup language and +Sphinx_ for generating the documentation in the formats read by the end users, +such as HTML and PDF. reStructuredText ---------------- -reStructuredText *"is an easy-to-read, what-you-see-is-what-you-get plaintext -markup syntax and parser system"*. +reStructuredText is a plaintext markup syntax similar to Markdown, but much +stricter with its syntax. If you are new to reStructuredText, take some time to +familiarize with this format by reading the existing `Symfony documentation`_ -You can learn more about its syntax by reading existing Symfony `documents`_ -or by reading the `reStructuredText Primer`_ on the Sphinx website. +If you want to learn more about this format, check out the `reStructuredText Primer`_ +tutorial and the `reStructuredText Reference`_. .. caution:: @@ -24,14 +26,14 @@ or by reading the `reStructuredText Primer`_ on the Sphinx website. Sphinx ------ -Sphinx is a build system that adds some nice tools to create documentation -from reStructuredText documents. As such, it adds new directives and -interpreted text roles to the standard reST `markup`_. +Sphinx is a build system that provides tools to create documentation from +reStructuredText documents. As such, it adds new directives and interpreted text +roles to the standard reST markup. Read more about the `Sphinx Markup Constructs`_. Syntax Highlighting ~~~~~~~~~~~~~~~~~~~ -All code examples uses PHP as the default highlighted language. You can change +PHP is the default syntax highlight applied to all code blocks. You can change it with the ``code-block`` directive: .. code-block:: rst @@ -41,7 +43,7 @@ it with the ``code-block`` directive: { foo: bar, bar: { foo: bar, bar: baz } } If your PHP code begins with ``` -You can also add links to the API documentation: +.. note:: + + Although they are technically correct, avoid the use of relative internal + links such as the following, because they break the references in the + generated PDF documentation: + + .. code-block:: rst + + :doc:`controller` + + :doc:`event_dispatcher/introduction` + + :doc:`environments` + +**Links to the API** follow a different syntax, where you must specify the type +of the linked resource (``namespace``, ``class`` or ``method``): .. code-block:: rst @@ -148,7 +166,7 @@ You can also add links to the API documentation: :method:`Symfony\\Component\\HttpKernel\\Bundle\\Bundle::build` -and to the PHP documentation: +**Links to the PHP documentation** follow a pretty similar syntax: .. code-block:: rst @@ -158,20 +176,55 @@ and to the PHP documentation: :phpfunction:`iterator_to_array` -Testing Documentation -~~~~~~~~~~~~~~~~~~~~~ +New Features or Behavior Changes +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -To test documentation before a commit: +If you're documenting a brand new feature or a change that's been made in +Symfony, you should precede your description of the change with a +``.. versionadded:: 2.X`` directive and a short description: -* Install `Sphinx`_; -* Install the Sphinx extensions using git submodules: ``git submodule update --init``; -* (Optionally) Install the bundle docs and CMF docs: ``bash install.sh``; -* Run ``make html`` and view the generated HTML in the ``build`` directory. +.. code-block:: text + + .. versionadded:: 2.3 + The ``askHiddenResponse`` method was introduced in Symfony 2.3. + + You can also ask a question and hide the response. This is particularly [...] + +If you're documenting a behavior change, it may be helpful to *briefly* describe +how the behavior has changed. + +.. code-block:: text + + .. versionadded:: 2.3 + The ``include()`` function is a new Twig feature that's available in + Symfony 2.3. Prior, the ``{% include %}`` tag was used. + +Whenever a new minor version of Symfony is released (e.g. 2.4, 2.5, etc), +a new branch of the documentation is created from the ``master`` branch. +At this point, all the ``versionadded`` tags for Symfony versions that have +reached end-of-life will be removed. For example, if Symfony 2.5 were released +today, and 2.2 had recently reached its end-of-life, the 2.2 ``versionadded`` +tags would be removed from the new 2.5 branch. + +Testing Documentation +~~~~~~~~~~~~~~~~~~~~~ -.. _reStructuredText: http://docutils.sourceforge.net/rst.html -.. _Sphinx: http://sphinx-doc.org/ -.. _documents: https://github.com/symfony/symfony-docs -.. _reStructuredText Primer: http://sphinx-doc.org/rest.html -.. _markup: http://sphinx-doc.org/markup/ -.. _Pygments website: http://pygments.org/languages/ -.. _Sphinx quick setup: http://sphinx-doc.org/tutorial.html#setting-up-the-documentation-sources +When submitting a new content to the documentation repository or when changing +any existing resource, an automatic process will check if your documentation is +free of syntax errors and is ready to be reviewed. + +Nevertheless, if you prefer to do this check locally on your own machine before +submitting your documentation, follow these steps: + +* Install Sphinx_; +* Install the Sphinx extensions using git submodules: ``$ git submodule update --init``; +* (Optionally) Install the bundle docs and CMF docs: ``$ bash install.sh``; +* Run ``make html`` and view the generated HTML in the ``build/`` directory. + +.. _reStructuredText: http://docutils.sourceforge.net/rst.html +.. _Sphinx: http://sphinx-doc.org/ +.. _`Symfony documentation`: https://github.com/symfony/symfony-docs +.. _`reStructuredText Primer`: http://sphinx-doc.org/rest.html +.. _`reStructuredText Reference`: http://docutils.sourceforge.net/docs/user/rst/quickref.html +.. _`Sphinx Markup Constructs`: http://sphinx-doc.org/markup/ +.. _`supported languages`: http://pygments.org/languages/ diff --git a/contributing/documentation/license.rst b/contributing/documentation/license.rst index d2ee34b4077..c6e7e294846 100644 --- a/contributing/documentation/license.rst +++ b/contributing/documentation/license.rst @@ -3,8 +3,8 @@ Symfony Documentation License ============================= -The Symfony documentation is licensed under a Creative Commons -Attribution-Share Alike 3.0 Unported `License`_. +The Symfony2 documentation is licensed under a Creative Commons +Attribution-Share Alike 3.0 Unported License (`CC BY-SA 3.0`_). **You are free:** @@ -48,5 +48,5 @@ Attribution-Share Alike 3.0 Unported `License`_. This is a human-readable summary of the `Legal Code (the full license)`_. -.. _License: http://creativecommons.org/licenses/by-sa/3.0/ +.. _`CC BY-SA 3.0`: http://creativecommons.org/licenses/by-sa/3.0/ .. _Legal Code (the full license): http://creativecommons.org/licenses/by-sa/3.0/legalcode diff --git a/contributing/documentation/overview.rst b/contributing/documentation/overview.rst index cb91c8b9111..c50c29be5f2 100644 --- a/contributing/documentation/overview.rst +++ b/contributing/documentation/overview.rst @@ -1,101 +1,102 @@ Contributing to the Documentation ================================= -Documentation is as important as code. It follows the exact same principles: -DRY, tests, ease of maintenance, extensibility, optimization, and refactoring -just to name a few. And of course, documentation has bugs, typos, hard to read -tutorials, and more. +One of the essential principles of the Symfony project is that **documentation is +as important as code**. That's why a great amount of resources are dedicated to +documenting new features and to keeping the rest of the documentation up to date. -Contributing ------------- +More than 800 developers all around the world have contributed to Symfony's +documentation, and we are glad that you are considering joining this big family. +This guide will explain everything you need to contribute to the Symfony +documentation. -Before contributing, you need to become familiar with the :doc:`markup -language ` used by the documentation. +Before Your First Contribution +------------------------------ -The Symfony documentation is hosted on GitHub: +**Before contributing**, you should consider the following: -.. code-block:: text - - https://github.com/symfony/symfony-docs +* Symfony documentation is written using reStructuredText_ markup language. + If you are not familiar with this format, read :doc:`this article ` + for a quick overview of its basic features. +* Symfony documentation is hosted on GitHub_. You'll need a GitHub user account + to contribute to the documentation. +* Symfony documentation is published under a + :doc:`Creative Commons BY-SA 3.0 License ` + and all your contributions will implicitly adhere to that license. -If you want to submit a patch, `fork`_ the official repository on GitHub and -then clone your fork: +Your First Documentation Contribution +------------------------------------- -.. code-block:: bash +In this section you'll learn how to contribute to the Symfony documentation for +the first time. The next section will explain the shorter process you'll follow +in the future for every contribution after your first. - $ git clone git://github.com/YOURUSERNAME/symfony-docs.git +Let's imagine that you want to improve the installation chapter of the Symfony +book. In order to make your changes, follow these steps: -Consistent with Symfony's source code, the documentation repository is split into -multiple branches, corresponding to the different versions of Symfony itself. -The ``master`` branch holds the documentation for the development branch of the code. +**Step 1.** Go to the official Symfony documentation repository located at +`github.com/symfony/symfony-docs`_ and `fork the repository`_ to your personal +account. This is only needed the first time you contribute to Symfony. -Unless you're documenting a feature that was introduced *after* Symfony 2.3 -(e.g. in Symfony 2.4), your changes should always be based on the 2.3 branch. -To do this checkout the 2.3 branch before the next step: +**Step 2.** **Clone** the forked repository to your local machine (this +example uses the ``projects/symfony-docs/`` directory to store the documentation; +change this value accordingly): .. code-block:: bash - $ git checkout 2.3 - -.. tip:: - - Your base branch (e.g. 2.3) will become the "Applies to" in the :ref:`doc-contributing-pr-format` - that you'll use later. + $ cd projects/ + $ git clone git://github.com//symfony-docs.git -Next, create a dedicated branch for your changes (for organization): +**Step 3.** Switch to the **oldest maintained branch** before making any change. +Nowadays this is the ``2.3`` branch: .. code-block:: bash - $ git checkout -b improving_foo_and_bar - -You can now make your changes directly to this branch and commit them. When -you're done, push this branch to *your* GitHub fork and initiate a pull request. - -Creating a Pull Request -~~~~~~~~~~~~~~~~~~~~~~~ - -Following the example, the pull request will default to be between your -``improving_foo_and_bar`` branch and the ``symfony-docs`` ``master`` branch. + $ cd symfony-docs/ + $ git checkout 2.3 -If you have made your changes based on the 2.3 branch then you need to change -the base branch to be 2.3 on the preview page by clicking the ``edit`` button -on the top left: +If you are instead documenting a new feature, switch to the first Symfony +version which included it: ``2.5``, ``2.6``, etc. -.. image:: /images/contributing/docs-pull-request-change-base.png - :align: center +**Step 4.** Create a dedicated **new branch** for your changes. This greatly +simplifies the work of reviewing and merging your changes. Use a short and +memorable name for the new branch: -.. note:: +.. code-block:: bash - All changes made to a branch (e.g. 2.3) will be merged up to each "newer" - branch (e.g. 2.4, master, etc) for the next release on a weekly basis. + $ git checkout -b improve_install_chapter -GitHub covers the topic of `pull requests`_ in detail. +**Step 5.** Now make your changes in the documentation. Add, tweak, reword and +even remove any content, but make sure that you comply with the +doc:`/contributing/documentation/standards`. -.. note:: +**Step 6.** **Push** the changes to your forked repository: - The Symfony documentation is licensed under a Creative Commons - Attribution-Share Alike 3.0 Unported :doc:`License `. +.. code-block:: bash -You can also prefix the title of your pull request in a few cases: + $ git commit book/installation.rst + $ git push origin improve_install_chapter -* ``[WIP]`` (Work in Progress) is used when you are not yet finished with your - pull request, but you would like it to be reviewed. The pull request won't - be merged until you say it is ready. +**Step 7.** Everything is now ready to initiate a **pull request**. Go to your +forked repository at ``https//github.com//symfony-docs`` +and click on the ``Pull Requests`` link located in the sidebar. -* ``[WCM]`` (Waiting Code Merge) is used when you're documenting a new feature - or change that hasn't been accepted yet into the core code. The pull request - will not be merged until it is merged in the core code (or closed if the - change is rejected). +Then, click on the big ``New pull request`` button. As GitHub cannot guess the +exact changes that you want to propose, select the appropriate branches where +changes should be applied:º -.. _doc-contributing-pr-format: +.. image:: /images/contributing/docs-pull-request-change-base.png + :align: center -Pull Request Format -~~~~~~~~~~~~~~~~~~~ +In this example, the **base repository** should be ``symfony/symfony-docs`` and +the **base branch** should be the ``2.3``, which is the branch that you selected +to base your changes on. The **compare repository** should be your forked copy +of ``symfony-docs`` and the **compare branch** should be ``improve_install_chapter``, +which is the name of the branch you created and where you made your changes. -Unless you're fixing some minor typos, the pull request description **must** -include the following checklist to ensure that contributions may be reviewed -without needless feedback loops and that your contributions can be included -into the documentation as quickly as possible: +**Step 8.** The last step is to prepare the **description** of the pull request. +To ensure that your work is reviewed quickly, please add the following table +at the beginning of your pull request description: .. code-block:: text @@ -106,123 +107,198 @@ into the documentation as quickly as possible: | Applies to | [Symfony version numbers this applies to] | Fixed tickets | [comma separated list of tickets fixed by the PR] -An example submission could now look as follows: +In this example, this table would look as follows: .. code-block:: text | Q | A | ------------- | --- | Doc fix? | yes - | New docs? | yes (symfony/symfony#2500) - | Applies to | all (or 2.3+) - | Fixed tickets | #1075 + | New docs? | no + | Applies to | all + | Fixed tickets | #10575 -.. tip:: +**Step 9.** Now that you've successfully submitted your first contribution to the +Symfony documentation, **go and celebrate!** The documentation managers will +carefully review your work in short time and they will let you know about any +required change. - Please be patient. It can take from 15 minutes to several days for your changes - to appear on the symfony.com website after the documentation team merges your - pull request. You can check if your changes have introduced some markup issues - by going to the `Documentation Build Errors`_ page (it is updated each French - night at 3AM when the server rebuilds the documentation). +In case you need to add or modify anything, there is no need to create a new +pull request. Just make sure that you are on the correct branch, make your +changes and push them: -Documenting new Features or Behavior Changes --------------------------------------------- +.. code-block:: bash -If you're documenting a brand new feature or a change that's been made in -Symfony, you should precede your description of the change with a ``.. versionadded:: 2.X`` -tag and a short description: + $ cd projects/symfony-docs/ + $ git checkout improve_install_chapter -.. code-block:: text + # ... do your changes - .. versionadded:: 2.3 - The ``askHiddenResponse`` method was introduced in Symfony 2.3. + $ git push - You can also ask a question and hide the response. This is particularly... +**Step 10.** After your pull request is eventually accepted and merged in the Symfony +documentation, you will be included in the `Symfony Documentation Contributors`_ +list. Moreover, if you happen to have a SensioLabsConnect_ profile, you will +get a cool `Symfony Documentation Badge`_. -If you're documenting a behavior change, it may be helpful to *briefly* describe -how the behavior has changed. +Your Second Documentation Contribution +-------------------------------------- -.. code-block:: text +The first contribution took some time because you had to fork the repository, +learn how to write documentation, comply with the pull requests standards, etc. +The second contribution will be much easier, except for one detail: given the +furious update activity of the Symfony documentation repository, odds are that +your fork is now out of date with the official repository. + +Solving this problem requires you to `sync your fork`_ with the original repository. +To do this, execute this command first to tell git about the original repository: + +.. code-block:: bash + + $ cd projects/symfony-docs/ + $ git remote add upstream https://github.com/symfony/symfony-docs.git + +Now you can **sync your fork** by executing the following command: + +.. code-block:: bash + + $ cd projects/symfony-docs/ + $ git fetch upstream + $ git checkout master + $ git merge upstream/master - .. versionadded:: 2.3 - The ``include()`` function is a new Twig feature that's available in - Symfony 2.3. Prior, the ``{% include %}`` tag was used. +Great! Now you can proceed by following the same steps explained in the previous +section: -Whenever a new minor version of Symfony is released (e.g. 2.4, 2.5, etc), -a new branch of the documentation is created from the ``master`` branch. -At this point, all the ``versionadded`` tags for Symfony versions that have -reached end-of-life will be removed. For example, if Symfony 2.5 were released -today, and 2.2 had recently reached its end-of-life, the 2.2 ``versionadded`` -tags would be removed from the new 2.5 branch. +.. code-block:: bash -Standards ---------- + # create a new branch to store your changes based on the 2.3 branch + $ cd projects/symfony-docs/ + $ git checkout 2.3 + $ git checkout -b my_changes + + # ... do your changes + + # submit the changes to your forked repository + $ git add xxx.rst # (optional) only if this is a new content + $ git commit xxx.rst + $ git push + + # go to GitHub and create the Pull Request + # + # Include this table in the description: + # | Q | A + # | ------------- | --- + # | Doc fix? | [yes|no] + # | New docs? | [yes|no] (PR # on symfony/symfony if applicable) + # | Applies to | [Symfony version numbers this applies to] + # | Fixed tickets | [comma separated list of tickets fixed by the PR] + +Your second contribution is now complete, so **go and celebrate again!** +You can also see how your ranking improves in the list of +`Symfony Documentation Contributors`_. + +Your Next Documentation Contributions +------------------------------------- + +Now that you've made two contributions to the Symfony documentation, you are +probably comfortable with all the Git-magic involved in the process. That's +why your next contributions would be much faster. Here you can find the complete +steps to contribute to the Symfony documentation, which you can use as a +**checklist**: -All documentation in the Symfony Documentation should follow -:doc:`the documentation standards `. +.. code-block:: bash -Reporting an Issue ------------------- + # sync your fork with the official Symfony repository + $ cd projects/symfony-docs/ + $ git fetch upstream + $ git checkout master + $ git merge upstream/master -The most easy contribution you can make is reporting issues: a typo, a grammar -mistake, a bug in a code example, a missing explanation, and so on. + # create a new branch from the oldest maintained version + $ git checkout 2.3 + $ git checkout -b my_changes -Steps: + # ... do your changes -* Submit a bug in the bug tracker; + # add and commit your changes + $ git add xxx.rst # (optional) only if this is a new content + $ git commit xxx.rst + $ git push -* *(optional)* Submit a patch. + # go to GitHub and create the Pull Request + # + # Include this table in the description: + # | Q | A + # | ------------- | --- + # | Doc fix? | [yes|no] + # | New docs? | [yes|no] (PR # on symfony/symfony if applicable) + # | Applies to | [Symfony version numbers this applies to] + # | Fixed tickets | [comma separated list of tickets fixed by the PR] -Translating ------------ + # (optional) make the changes requested by reviewers and commit them + $ git commit xxx.rst + $ git push -Read the dedicated :doc:`document `. +You guessed right: after all this hard work, it's **time to celebrate again!** -Managing Releases ------------------ +Frequently Asked Questions +-------------------------- -Symfony has a very standardized release process, which you can read more -about in the :doc:`/contributing/community/releases` section. +Why Do my Changes Take so Long to Be Reviewed and/or Merged? +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -To keep up with the release process, the documentation team makes several -changes to the documentation at various parts of the lifecycle. +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. -When a Release Reaches "End of Maintenance" -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +What If I Want to Translate Some Documentation into my Language? +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -Every release will eventually reach its "end of maintenance". For details, -see :ref:`contributing-release-maintenance`. +Read the dedicated :doc:`document `. -When a release reaches its end of maintenance, the following items are done. -For this example, suppose version 2.1 has just reached its end of maintenance: +Why Should I Use the Oldest Maintained Branch Instead of the Master Branch? +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -* Changes and pull requests are no longer merged into to the branch (2.1), - except for security updates, which are merged until the release reaches - its "end of life". +Consistent with Symfony's source code, the documentation repository is split +into multiple branches, corresponding to the different versions of Symfony itself. +The master branch holds the documentation for the development branch of the code. -* All branches still under maintenance (e.g. 2.2 and higher) are updated - to reflect that pull requests should start from the now-oldest maintained - version (e.g. 2.2) - including the details in the README file. +Unless you're documenting a feature that was introduced after Symfony 2.3, +your changes should always be based on the 2.3 branch. Documentation managers +will use the necessary Git-magic to also apply your changes to all the active +branches of the documentation. -* Remove all ``versionadded`` directives - and any other notes related to features - changing or being new - for the version (e.g. 2.1) from the master branch. - The result is that the next release (which is the first that comes entirely - *after* the end of maintenance of this branch), will have no mentions of - the old version (e.g. 2.1). +What If I Want to Submit my Work without Fully Finishing It? +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -When a new Branch is Created for a Release -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +You can do it. But please use one of these two prefixes to let reviewers know +about the state of your work: -During the :ref:`stabilization phase `, a -new branch on the documentation is created. For example, if version 2.3 were -being stabilized, then a new 2.3 branch would be created for it. When this -happens, the following items are done: +* ``[WIP]`` (Work in Progress) is used when you are not yet finished with your + pull request, but you would like it to be reviewed. The pull request won't + be merged until you say it is ready. -* Change all version and master references to the correct version (e.g. 2.3). - For example, in installation chapters, we reference the version you should - use for installation. As an example, see the changes made in `PR #2688`_. +* ``[WCM]`` (Waiting Code Merge) is used when you're documenting a new feature + or change that hasn't been accepted yet into the core code. The pull request + will not be merged until it is merged in the core code (or closed if the + change is rejected). -.. _`fork`: https://help.github.com/articles/fork-a-repo -.. _`pull requests`: https://help.github.com/articles/using-pull-requests -.. _`Documentation Build Errors`: http://symfony.com/doc/build_errors -.. _`PR #2688`: https://github.com/symfony/symfony-docs/pull/2688 +Would You Accept a Huge Pull Request with Lots of Changes? +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +First, make sure that the changes are somewhat related. Otherwise, please create +separate pull requests. Anyway, before submitting a huge change, it's probably a +good idea to open an issue in the Symfony Documentation repository to ask the +managers if they agree with your proposed changes. Otherwise, they could refuse +your proposal after you put all that hard work into making the changes. We +definitely don't want you to waste your time! + +.. _`github.com/symfony/symfony-docs`: https://github.com/symfony/symfony-docs +.. _reStructuredText: http://docutils.sourceforge.net/rst.html +.. _GitHub: https://github.com/ +.. _`fork the repository`: https://help.github.com/articles/fork-a-repo +.. _`Symfony Documentation Contributors`: http://symfony.com/contributors/doc +.. _SensioLabsConnect: https://connect.sensiolabs.com/ +.. _`Symfony Documentation Badge`: https://connect.sensiolabs.com/badge/36/symfony-documentation-contributor +.. _`sync your fork`: https://help.github.com/articles/syncing-a-fork diff --git a/contributing/documentation/standards.rst b/contributing/documentation/standards.rst index 7e888fd9796..39d073ec0da 100644 --- a/contributing/documentation/standards.rst +++ b/contributing/documentation/standards.rst @@ -43,7 +43,7 @@ Example echo 'You cannot use the :: shortcut here'; - .. _`Symfony Documentation`: http://symfony.com/doc/current/contributing/documentation/standards.html + .. _`Symfony Documentation`: http://symfony.com/doc Code Examples ------------- @@ -134,19 +134,23 @@ Files and Directories ├─ vendor/ └─ ... -Language Standards ------------------- +English Language Standards +-------------------------- -* For sections, use the following capitalization rules: - `Capitalization of the first word, and all other words, except for closed-class words`_: +* **English Dialect**: use the United States English dialect, commonly called + `American English`_. +* **Section titles**: use a variant of the title case, where the first + word is always capitalized and all other words are capitalized, except for + the closed-class words (read Wikipedia article about `headings and titles`_). - The Vitamins are in my Fresh California Raisins + E.g.: The Vitamins are in my Fresh California Raisins -* Do not use `Serial (Oxford) Commas`_; -* You should use a form of *you* instead of *we* (i.e. avoid the first person - point of view: use the second instead); -* When referencing a hypothetical person, such as "a user with a session cookie", gender-neutral - pronouns (they/their/them) should be used. For example, instead of: +* **Punctuation**: avoid the use of `Serial (Oxford) Commas`_; +* **Pronouns**: avoid the use of `nosism`_ and always use *you* instead of *we*. + (i.e. avoid the first person point of view: use the second instead); +* **Gender-neutral language**: when referencing a hypothetical person, such as + *"a user with a session cookie"*, use gender-neutral pronouns (they/their/them). + For example, instead of: * he or she, use they * him or her, use them * his or her, use their @@ -155,5 +159,7 @@ Language Standards .. _`the Sphinx documentation`: http://sphinx-doc.org/rest.html#source-code .. _`Twig Coding Standards`: http://twig.sensiolabs.org/doc/coding_standards.html -.. _`Capitalization of the first word, and all other words, except for closed-class words`: http://en.wikipedia.org/wiki/Letter_case#Headings_and_publication_titles +.. _`American English`: http://en.wikipedia.org/wiki/American_English +.. _`headings and titles`: http://en.wikipedia.org/wiki/Letter_case#Headings_and_publication_titles .. _`Serial (Oxford) Commas`: http://en.wikipedia.org/wiki/Serial_comma +.. _`nosism`: http://en.wikipedia.org/wiki/Nosism diff --git a/contributing/documentation/translations.rst b/contributing/documentation/translations.rst index cc6838dbccb..54c5002ff54 100644 --- a/contributing/documentation/translations.rst +++ b/contributing/documentation/translations.rst @@ -4,11 +4,17 @@ Translations The Symfony documentation is written in English and many people are involved in the translation process. +.. note:: + + Symfony Project officially discourages 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 ` used by the -documentation. +First, become familiar with the :doc:`markup language ` +used by the documentation. Then, subscribe to the `Symfony docs mailing-list`_, as collaboration happens there. @@ -20,9 +26,7 @@ for. Here is the list of the official *master* repositories: * *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 -* *Polish*: https://github.com/symfony-docs-pl/symfony-docs-pl * *Portuguese (Brazilian)*: https://github.com/andreia/symfony-docs-pt-BR -* *Spanish*: https://github.com/gitnacho/symfony-docs-es .. note:: @@ -84,4 +88,5 @@ repository and apply changes to the translated documents as soon as possible. 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 .. _Symfony docs mailing-list: http://groups.google.com/group/symfony-docs diff --git a/cookbook/deployment/tools.rst b/cookbook/deployment/tools.rst index 5f6a9991a65..76992a17c59 100644 --- a/cookbook/deployment/tools.rst +++ b/cookbook/deployment/tools.rst @@ -110,6 +110,12 @@ as you normally do: ensures that development packages are not installed in the production environment. +.. caution:: + + If you get a "class not found" error during this step, you may need to + run ``export SYMFONY_ENV=prod`` before running this command so that + the ``post-install-cmd`` scripts run in the ``prod`` environment. + D) Clear your Symfony Cache ~~~~~~~~~~~~~~~~~~~~~~~~~~~ diff --git a/cookbook/security/entity_provider.rst b/cookbook/security/entity_provider.rst index 5943ea396c5..ae32cc78a4c 100644 --- a/cookbook/security/entity_provider.rst +++ b/cookbook/security/entity_provider.rst @@ -651,6 +651,14 @@ about in this section. If you fail to return any roles, it may appear as if your user isn't authenticated at all. +.. caution:: + + In order to work with the security configuration examples on this page + all roles must be prefixed with ``ROLE_`` (see + the :ref:`section about roles ` in the book). For + example, your roles will be ``ROLE_ADMIN`` or ``ROLE_USER`` instead of + ``ADMIN`` or ``USER``. + In this example, the ``AcmeUserBundle:User`` entity class defines a many-to-many relationship with a ``AcmeUserBundle:Role`` entity class. A user can be related to several roles and a role can be composed of diff --git a/cookbook/templating/PHP.rst b/cookbook/templating/PHP.rst index b3b142d1016..9d09afbfa4b 100644 --- a/cookbook/templating/PHP.rst +++ b/cookbook/templating/PHP.rst @@ -77,6 +77,33 @@ shortcut to render the default ``AcmeHelloBundle:Hello:index.html.php`` template return array('name' => $name); } +.. caution:: + + Enabling the ``php`` and ``twig`` template engines simultaneously is + allowed, but it will produce an undesirable side effect in your application: + the ``@`` notation for Twig namespaces will no longer be supported for the + ``render()`` method:: + + public function indexAction() + { + // ... + + // namespaced templates will no longer work in controllers + $this->render('@Acme/Default/index.html.twig'); + + // you must use the traditional template notation + $this->render('AcmeBundle:Default:index.html.twig'); + } + + .. code-block:: jinja + + {# inside a Twig template, namespaced templates work as expected #} + {{ include('@Acme/Default/index.html.twig') }} + + {# traditional template notation will also work #} + {{ include('AcmeBundle:Default:index.html.twig') }} + + .. index:: single: Templating; Layout single: Layout diff --git a/reference/constraints/Expression.rst b/reference/constraints/Expression.rst index 5db3373b55e..68526372837 100644 --- a/reference/constraints/Expression.rst +++ b/reference/constraints/Expression.rst @@ -217,6 +217,13 @@ more about the expression language syntax, see // ... } + .. caution:: + + In Symfony 2.4 and Symfony 2.5, if the property (e.g. ``isTechnicalPost``) + were ``null``, the expression would never be called and the value + would be seen as valid. To ensure that the value is not ``null``, + use the :doc:`NotNull constraint `. + For more information about the expression and what variables are available to you, see the :ref:`expression ` option details below.