Merge branch '2.7' into 2.8

weaverryan · weaverryan · commit bc007412b7a3 · 2016-08-20T19:54:30.000-04:00
* 2.7:
  Adding details about the Symfony framework as comments
  Adjust Application use statement
  replacing with index, otherwise these documents are not included in *any* index
  Removed the "Learn more" section
  Created a "Platform as a Service" section
  Minor improvements
  Fixed the "make" command
  Fixed again the tricky list syntax
  Fixed the syntax of the list
  Minor fixes
  Reword the third step
  Added the missing link references
  Updated the instructions to build docs locally
  Refactore how to get the container in a test
  Fixed a reference
  Created the main article about "deployment"
diff --git a/_build/redirection_map b/_build/redirection_map
@@ -328,4 +328,5 @@
 /components/var_dumper/index /components/var_dumper
 /components/yaml/introduction /components/yaml
 /components/yaml/index /components/yaml
+/deployment/tools /deployment
 /install/bundles /setup/bundles
diff --git a/console.rst b/console.rst
@@ -216,14 +216,22 @@ console::
     namespace Tests\AppBundle\Command;
 
     use AppBundle\Command\CreateUserCommand;
-    use Symfony\Bundle\FrameworkBundle\Console\Application;
+    use Symfony\Component\Console\Application;
+    // use this if you're in the Symfony Framework
+    //use Symfony\Bundle\FrameworkBundle\Console\Application;
     use Symfony\Component\Console\Tester\CommandTester;
 
     class CreateUserCommandTest extends \PHPUnit_Framework_TestCase
     {
         public function testExecute()
         {
             $application = new Application();
+
+            // if you're in the Symfony framework, do this instead
+            // extend the KernelTestCase class
+            // self::bootKernel();
+            // $application = new Application(self::$kernel);
+
             $application->add(new CreateUserCommand());
 
             $command = $application->find('app:create-user');
@@ -251,13 +259,6 @@ console::
     You can also test a whole console application by using
     :class:`Symfony\\Component\\Console\\Tester\\ApplicationTester`.
 
-.. note::
-
-    When using the Console component in a standalone project, use
-    :class:`Symfony\\Component\\Console\\Application <Symfony\\Component\\Console\\Application>`
-    instead of
-    :class:`Symfony\\Bundle\\FrameworkBundle\\Console\\Application <Symfony\\Bundle\\FrameworkBundle\\Console\\Application>`
-
 To be able to use the fully set up service container for your console tests
 you can extend your test from
 :class:`Symfony\\Bundle\\FrameworkBundle\\Test\\KernelTestCase`::
diff --git a/contributing/documentation/format.rst b/contributing/documentation/format.rst
@@ -27,7 +27,7 @@ tutorial and the `reStructuredText Reference`_.
 Sphinx
 ------
 
-Sphinx is a build system that provides tools to create documentation from
+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`_.
 
@@ -198,20 +198,6 @@ reached end-of-maintenance 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
-~~~~~~~~~~~~~~~~~~~~~
-
-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``;
-* Run ``make html`` and view the generated HTML in the ``_build/html`` directory.
-
 .. _reStructuredText: http://docutils.sourceforge.net/rst.html
 .. _Sphinx: http://sphinx-doc.org/
 .. _`Symfony documentation`: https://github.com/symfony/symfony-docs
diff --git a/contributing/documentation/overview.rst b/contributing/documentation/overview.rst
@@ -258,6 +258,33 @@ link displayed for Platform.sh service.
     Only Pull Requests to maintained branches are automatically built by
     Platform.sh. Check the `roadmap`_ for maintained branches.
 
+Build the Documentation Locally
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Alternatively you can build the documentation in your own computer for testing
+purposes following these steps:
+
+#. Install `pip`_ as explained in the `pip installation`_ article.
+
+#. Install `Sphinx`_ and `Sphinx Extensions for PHP and Symfony`_
+   (depending on your system, you may need to execute this command as root user):
+
+   .. code-block:: bash
+
+        $ pip install sphinx~=1.3.0 git+https://github.com/fabpot/sphinx-php.git
+
+#. Run the following command to build the documentation in HTML format:
+
+   .. code-block:: bash
+
+       # Linux and macOS
+       $ ./_build/make html
+
+       # Windows
+       $ _build\make html
+
+The generated documentation is available in the ``_build/html`` directory.
+
 Frequently Asked Questions
 --------------------------
 
@@ -316,3 +343,7 @@ definitely don't want you to waste your time!
 .. _`sync your fork`: https://help.github.com/articles/syncing-a-fork
 .. _`Platform.sh`: https://platform.sh
 .. _`roadmap`: https://symfony.com/roadmap
+.. _`pip`: https://pip.pypa.io/en/stable/
+.. _`pip installation`: https://pip.pypa.io/en/stable/installing/
+.. _`Sphinx`: http://sphinx-doc.org/
+.. _`Sphinx Extensions for PHP and Symfony`: https://github.com/fabpot/sphinx-php
diff --git a/deployment.rst b/deployment.rst
@@ -1,8 +1,210 @@
-Deployment
-==========
+.. index::
+   single: Deployment; Deployment tools
+
+.. _how-to-deploy-a-symfony2-application:
+
+How to Deploy a Symfony Application
+===================================
+
+Deploying a Symfony application can be a complex and varied task depending on
+the setup and the requirements of your application. This article is not a step-
+by-step guide, but is a general list of the most common requirements and ideas
+for deployment.
+
+.. _symfony2-deployment-basics:
+
+Symfony Deployment Basics
+-------------------------
+
+The typical steps taken while deploying a Symfony application include:
+
+#. Upload your code to the production server;
+#. Install your vendor dependencies (typically done via Composer and may be done
+   before uploading);
+#. Running database migrations or similar tasks to update any changed data structures;
+#. Clearing (and optionally, warming up) your cache.
+
+A deployment may also include other tasks, such as:
+
+* Tagging a particular version of your code as a release in your source control
+  repository;
+* Creating a temporary staging area to build your updated setup "offline";
+* Running any tests available to ensure code and/or server stability;
+* Removal of any unnecessary files from the ``web/`` directory to keep your
+  production environment clean;
+* Clearing of external cache systems (like `Memcached`_ or `Redis`_).
+
+How to Deploy a Symfony Application
+-----------------------------------
+
+There are several ways you can deploy a Symfony application. Start with a few
+basic deployment strategies and build up from there.
+
+Basic File Transfer
+~~~~~~~~~~~~~~~~~~~
+
+The most basic way of deploying an application is copying the files manually
+via FTP/SCP (or similar method). This has its disadvantages as you lack control
+over the system as the upgrade progresses. This method also requires you
+to take some manual steps after transferring the files (see `Common Post-Deployment Tasks`_)
+
+Using Source Control
+~~~~~~~~~~~~~~~~~~~~
+
+If you're using source control (e.g. Git or SVN), you can simplify by having
+your live installation also be a copy of your repository. When you're ready
+to upgrade it is as simple as fetching the latest updates from your source
+control system.
+
+This makes updating your files *easier*, but you still need to worry about
+manually taking other steps (see `Common Post-Deployment Tasks`_).
+
+Using Platforms as a Service
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+The specific deployment steps vary greatly from one service provider to another,
+so check out the dedicated article for the service of your choose:
 
 .. toctree::
     :maxdepth: 1
     :glob:
 
     deployment/*
+
+Using Build Scripts and other Tools
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+There are also tools to help ease the pain of deployment. Some of them have been
+specifically tailored to the requirements of Symfony.
+
+`Capistrano`_ with `Symfony plugin`_
+    `Capistrano`_ is a remote server automation and deployment tool written in Ruby.
+    `Symfony plugin`_ is a plugin to ease Symfony related tasks, inspired by `Capifony`_
+    (which works only with Capistrano 2 )
+
+`sf2debpkg`_
+    Helps you build a native Debian package for your Symfony project.
+
+`Magallanes`_
+    This Capistrano-like deployment tool is built in PHP, and may be easier
+    for PHP developers to extend for their needs.
+
+`Fabric`_
+    This Python-based library provides a basic suite of operations for executing
+    local or remote shell commands and uploading/downloading files.
+
+`Deployer`_
+    This is another native PHP rewrite of Capistrano, with some ready recipes for
+    Symfony.
+
+Bundles
+    There are some `bundles that add deployment features`_ directly into your
+    Symfony console.
+
+Basic scripting
+    You can of course use shell, `Ant`_ or any other build tool to script
+    the deploying of your project.
+
+Common Post-Deployment Tasks
+----------------------------
+
+After deploying your actual source code, there are a number of common things
+you'll need to do:
+
+A) Check Requirements
+~~~~~~~~~~~~~~~~~~~~~
+
+Check if your server meets the requirements by running:
+
+.. code-block:: bash
+
+    $ php app/check.php
+
+B) Configure your ``app/config/parameters.yml`` File
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+This file should *not* be deployed, but managed through the automatic utilities
+provided by Symfony.
+
+C) Install/Update your Vendors
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Your vendors can be updated before transferring your source code (i.e.
+update the ``vendor/`` directory, then transfer that with your source
+code) or afterwards on the server. Either way, just update your vendors
+as you normally do:
+
+.. code-block:: bash
+
+    $ composer install --no-dev --optimize-autoloader
+
+.. tip::
+
+    The ``--optimize-autoloader`` flag improves Composer's autoloader performance
+    significantly by building a "class map". The ``--no-dev`` flag 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
+~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Make sure you clear (and warm-up) your Symfony cache:
+
+.. code-block:: bash
+
+    $ php app/console cache:clear --env=prod --no-debug
+
+E) Dump your Assetic Assets
+~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+If you're using Assetic, you'll also want to dump your assets:
+
+.. code-block:: bash
+
+    $ php app/console assetic:dump --env=prod --no-debug
+
+F) Other Things!
+~~~~~~~~~~~~~~~~
+
+There may be lots of other things that you need to do, depending on your
+setup:
+
+* Running any database migrations
+* Clearing your APC cache
+* Running ``assets:install`` (already taken care of in ``composer install``)
+* Add/edit CRON jobs
+* Pushing assets to a CDN
+* ...
+
+Application Lifecycle: Continuous Integration, QA, etc
+------------------------------------------------------
+
+While this entry covers the technical details of deploying, the full lifecycle
+of taking code from development up to production may have a lot more steps
+(think deploying to staging, QA (Quality Assurance), running tests, etc).
+
+The use of staging, testing, QA, continuous integration, database migrations
+and the capability to roll back in case of failure are all strongly advised. There
+are simple and more complex tools and one can make the deployment as easy
+(or sophisticated) as your environment requires.
+
+Don't forget that deploying your application also involves updating any dependency
+(typically via Composer), migrating your database, clearing your cache and
+other potential things like pushing assets to a CDN (see `Common Post-Deployment Tasks`_).
+
+.. _`Capifony`: http://capifony.org/
+.. _`Capistrano`: http://capistranorb.com/
+.. _`sf2debpkg`: https://github.com/liip/sf2debpkg
+.. _`Fabric`: http://www.fabfile.org/
+.. _`Magallanes`: https://github.com/andres-montanez/Magallanes
+.. _`Ant`: http://blog.sznapka.pl/deploying-symfony2-applications-with-ant
+.. _`bundles that add deployment features`: http://knpbundles.com/search?q=deploy
+.. _`Memcached`: http://memcached.org/
+.. _`Redis`: http://redis.io/
+.. _`Symfony plugin`: https://github.com/capistrano/symfony/
+.. _`Deployer`: http://deployer.org/
diff --git a/deployment/azure-website.rst b/deployment/azure-website.rst
@@ -392,7 +392,7 @@ MySQL database.
 
 This command builds the tables and indexes for your MySQL database. If your
 Symfony application is more complex than a basic Symfony Standard Edition, you
-may have additional commands to execute for setup (see :doc:`/deployment/tools`).
+may have additional commands to execute for setup (see :doc:`/deployment`).
 
 Make sure that your application is running by browsing the ``app.php`` front
 controller with your web browser and the following URL:
diff --git a/deployment/tools.rst b/deployment/tools.rst
diff --git a/testing.rst b/testing.rst
