From b297d290bd87d4d54dc77b990dfaf1a62b542c5a Mon Sep 17 00:00:00 2001 From: Javier Eguiluz Date: Fri, 22 Aug 2014 13:09:47 +0200 Subject: [PATCH 01/11] First draft of the bundle installation instructions --- cookbook/bundles/best_practices.rst | 47 +++++++++++++++++++++++++++++ 1 file changed, 47 insertions(+) diff --git a/cookbook/bundles/best_practices.rst b/cookbook/bundles/best_practices.rst index 055e0bee5a7..5aeed8da238 100644 --- a/cookbook/bundles/best_practices.rst +++ b/cookbook/bundles/best_practices.rst @@ -268,6 +268,53 @@ semantic configuration described in the cookbook. If you are defining services, they should also be prefixed with the bundle alias. +Installation instructions +------------------------- + +In order to ease the installation process of third-party bundles, we propose +you to use the following standardized instructions in your ``README`` file: + +.. code-block:: + + Installation + ============ + + Step 1: Download the bundle + --------------------------- + + Use Composer to add the bundle as a new dependency of your project: + + .. code-block:: bash + + $ composer require "/:dev-master" + + This command requires to have installed Composer globally, as explained + `in the installation chapter `_ + of Composer documentation. + + Step 2: Enable the bundle + ------------------------- + + Then, enable the bundle adding the following line in the ``AppKernel`` class + of your project: + + .. code-block:: php + + \\(), + ); + } + + (optionally add *Step 3*, *Step 4*, etc. to explain other required + installation steps, such as registering routes or dumping assets) + Learn more from the Cookbook ---------------------------- From 11db86045020bb698195d4a9125ea8f63e555078 Mon Sep 17 00:00:00 2001 From: Javier Eguiluz Date: Fri, 22 Aug 2014 17:52:17 +0200 Subject: [PATCH 02/11] Applied all the fixes and suggestions made by reviewers --- cookbook/bundles/best_practices.rst | 97 +++++++++++++++-------------- 1 file changed, 50 insertions(+), 47 deletions(-) diff --git a/cookbook/bundles/best_practices.rst b/cookbook/bundles/best_practices.rst index 5aeed8da238..ce3b044a3e5 100644 --- a/cookbook/bundles/best_practices.rst +++ b/cookbook/bundles/best_practices.rst @@ -194,6 +194,56 @@ Extensive documentation should also be provided in the the ``Resources/doc/`` directory; the ``Resources/doc/index.rst`` file is the only mandatory file and must be the entry point for the documentation. +Installation instructions +~~~~~~~~~~~~~~~~~~~~~~~~~ + +In order to ease the installation process of third-party bundles, we propose +you to use the following standardized instructions in your ``README`` file. + +.. sidebar:: Bundle Instructions Template + + .. raw:: rst + + Installation + ============ + + Step 1: Download the Bundle + --------------------------- + + Use Composer to add the bundle as a new dependency of your project: + + .. code-block:: bash + + $ composer require "/:dev-master" + + This command requires to have installed Composer globally, as explained + `in the installation chapter `_ + of Composer documentation. + + Step 2: Enable the Bundle + ------------------------- + + Then, enable the bundle adding the following line in the ``AppKernel`` + class of your project: + + .. code-block:: php + + \\(), + ); + } + + (optionally add *Step 3*, *Step 4*, etc. to explain other required + installation steps, such as registering routes or dumping assets) + + Routing ------- @@ -268,53 +318,6 @@ semantic configuration described in the cookbook. If you are defining services, they should also be prefixed with the bundle alias. -Installation instructions -------------------------- - -In order to ease the installation process of third-party bundles, we propose -you to use the following standardized instructions in your ``README`` file: - -.. code-block:: - - Installation - ============ - - Step 1: Download the bundle - --------------------------- - - Use Composer to add the bundle as a new dependency of your project: - - .. code-block:: bash - - $ composer require "/:dev-master" - - This command requires to have installed Composer globally, as explained - `in the installation chapter `_ - of Composer documentation. - - Step 2: Enable the bundle - ------------------------- - - Then, enable the bundle adding the following line in the ``AppKernel`` class - of your project: - - .. code-block:: php - - \\(), - ); - } - - (optionally add *Step 3*, *Step 4*, etc. to explain other required - installation steps, such as registering routes or dumping assets) - Learn more from the Cookbook ---------------------------- From 21ce2c0d06bb2dfb9c20099f794a6a8980b923c1 Mon Sep 17 00:00:00 2001 From: Javier Eguiluz Date: Fri, 22 Aug 2014 17:54:00 +0200 Subject: [PATCH 03/11] Fixed minor typo --- cookbook/bundles/best_practices.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/cookbook/bundles/best_practices.rst b/cookbook/bundles/best_practices.rst index ce3b044a3e5..9b3d11f4a6a 100644 --- a/cookbook/bundles/best_practices.rst +++ b/cookbook/bundles/best_practices.rst @@ -200,7 +200,7 @@ Installation instructions In order to ease the installation process of third-party bundles, we propose you to use the following standardized instructions in your ``README`` file. -.. sidebar:: Bundle Instructions Template +.. sidebar:: Installation Instructions Template .. raw:: rst From ed96447b44c94e51b587e7a8762c4c1dee217e86 Mon Sep 17 00:00:00 2001 From: Javier Eguiluz Date: Fri, 22 Aug 2014 18:17:42 +0200 Subject: [PATCH 04/11] More improvements based on reviewers' comments --- cookbook/bundles/best_practices.rst | 41 ++++++++++++++++------------- 1 file changed, 22 insertions(+), 19 deletions(-) diff --git a/cookbook/bundles/best_practices.rst b/cookbook/bundles/best_practices.rst index 9b3d11f4a6a..fee75b9d816 100644 --- a/cookbook/bundles/best_practices.rst +++ b/cookbook/bundles/best_practices.rst @@ -202,7 +202,10 @@ you to use the following standardized instructions in your ``README`` file. .. sidebar:: Installation Instructions Template - .. raw:: rst + This template assumes that your bundle is in its ``1.x`` version. If not, + change the ``"~1"`` installation version accordingly (e.g. ``"~2"``). + + .. raw:: md Installation ============ @@ -212,36 +215,36 @@ you to use the following standardized instructions in your ``README`` file. Use Composer to add the bundle as a new dependency of your project: - .. code-block:: bash - - $ composer require "/:dev-master" + ``` + $ composer require "~1" + ``` This command requires to have installed Composer globally, as explained - `in the installation chapter `_ + in the [installation chapter](https://getcomposer.org/doc/00-intro.md) of Composer documentation. Step 2: Enable the Bundle ------------------------- - Then, enable the bundle adding the following line in the ``AppKernel`` + Then, enable the bundle adding the following line in the `AppKernel` class of your project: - .. code-block:: php - - \\(), - ); - } + new \\(), + ); + } + ``` - (optionally add *Step 3*, *Step 4*, etc. to explain other required - installation steps, such as registering routes or dumping assets) + Optionally you can add *Step 3*, *Step 4*, etc. to explain other required + installation steps, such as registering routes or dumping assets. Routing From c39f7d3ebb02abb1a017f7b846a85e1a1c316d7d Mon Sep 17 00:00:00 2001 From: Javier Eguiluz Date: Fri, 22 Aug 2014 20:36:33 +0200 Subject: [PATCH 05/11] Fixed some code formatting --- cookbook/bundles/best_practices.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/cookbook/bundles/best_practices.rst b/cookbook/bundles/best_practices.rst index fee75b9d816..593012a38e3 100644 --- a/cookbook/bundles/best_practices.rst +++ b/cookbook/bundles/best_practices.rst @@ -198,14 +198,14 @@ Installation instructions ~~~~~~~~~~~~~~~~~~~~~~~~~ In order to ease the installation process of third-party bundles, we propose -you to use the following standardized instructions in your ``README`` file. +you to use the following standardized instructions in your ``README.md`` file. .. sidebar:: Installation Instructions Template This template assumes that your bundle is in its ``1.x`` version. If not, change the ``"~1"`` installation version accordingly (e.g. ``"~2"``). - .. raw:: md + .. code-block:: text Installation ============ From 322ec6069384e64b1fe8aae30d5e19900942b650 Mon Sep 17 00:00:00 2001 From: Javier Eguiluz Date: Fri, 22 Aug 2014 21:56:19 +0200 Subject: [PATCH 06/11] Removed the first person perspective and other minor fixes --- cookbook/bundles/best_practices.rst | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/cookbook/bundles/best_practices.rst b/cookbook/bundles/best_practices.rst index 593012a38e3..fd1f5ba973d 100644 --- a/cookbook/bundles/best_practices.rst +++ b/cookbook/bundles/best_practices.rst @@ -194,11 +194,11 @@ Extensive documentation should also be provided in the the ``Resources/doc/`` directory; the ``Resources/doc/index.rst`` file is the only mandatory file and must be the entry point for the documentation. -Installation instructions +Installation Instructions ~~~~~~~~~~~~~~~~~~~~~~~~~ -In order to ease the installation process of third-party bundles, we propose -you to use the following standardized instructions in your ``README.md`` file. +In order to ease the installation process of third-party bundles, consider using +the following standardized instructions in your ``README.md`` file. .. sidebar:: Installation Instructions Template From 4b29de2ab10ae8e9f75c6d5593cee833290db22a Mon Sep 17 00:00:00 2001 From: Javier Eguiluz Date: Fri, 22 Aug 2014 22:02:59 +0200 Subject: [PATCH 07/11] More tweaks and fixes --- cookbook/bundles/best_practices.rst | 7 ++++--- 1 file changed, 4 insertions(+), 3 deletions(-) diff --git a/cookbook/bundles/best_practices.rst b/cookbook/bundles/best_practices.rst index fd1f5ba973d..0072fa2b5f5 100644 --- a/cookbook/bundles/best_practices.rst +++ b/cookbook/bundles/best_practices.rst @@ -219,7 +219,7 @@ the following standardized instructions in your ``README.md`` file. $ composer require "~1" ``` - This command requires to have installed Composer globally, as explained + This command requires to have Composer installed globally, as explained in the [installation chapter](https://getcomposer.org/doc/00-intro.md) of Composer documentation. @@ -233,17 +233,18 @@ the following standardized instructions in your ``README.md`` file. \\(), ); } ``` - Optionally you can add *Step 3*, *Step 4*, etc. to explain other required + Optionally, you can add *Step 3*, *Step 4*, etc. to explain other required installation steps, such as registering routes or dumping assets. From 41ce2a55eab69064eae6d31f71c87720f92667b9 Mon Sep 17 00:00:00 2001 From: Javier Eguiluz Date: Sat, 23 Aug 2014 10:57:48 +0200 Subject: [PATCH 08/11] Minor fixes and tweaks --- cookbook/bundles/best_practices.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/cookbook/bundles/best_practices.rst b/cookbook/bundles/best_practices.rst index 0072fa2b5f5..736733a3204 100644 --- a/cookbook/bundles/best_practices.rst +++ b/cookbook/bundles/best_practices.rst @@ -215,7 +215,7 @@ the following standardized instructions in your ``README.md`` file. Use Composer to add the bundle as a new dependency of your project: - ``` + ```bash $ composer require "~1" ``` @@ -239,7 +239,7 @@ the following standardized instructions in your ``README.md`` file. { $bundles = array( // ... - new \\(), + return new \\(), ); } ``` From 7a6644be5317a2ebb8a0e5363b8534990d653e5d Mon Sep 17 00:00:00 2001 From: Javier Eguiluz Date: Sat, 23 Aug 2014 12:15:17 +0200 Subject: [PATCH 09/11] Removed the sidebar and made some minor tweaks --- cookbook/bundles/best_practices.rst | 72 ++++++++++++++--------------- 1 file changed, 35 insertions(+), 37 deletions(-) diff --git a/cookbook/bundles/best_practices.rst b/cookbook/bundles/best_practices.rst index 736733a3204..7ac545dfc43 100644 --- a/cookbook/bundles/best_practices.rst +++ b/cookbook/bundles/best_practices.rst @@ -197,56 +197,54 @@ the only mandatory file and must be the entry point for the documentation. Installation Instructions ~~~~~~~~~~~~~~~~~~~~~~~~~ -In order to ease the installation process of third-party bundles, consider using -the following standardized instructions in your ``README.md`` file. +In order to ease the installation of third-party bundles, consider using the +following standardized instructions in your ``README.md`` file. -.. sidebar:: Installation Instructions Template - - This template assumes that your bundle is in its ``1.x`` version. If not, - change the ``"~1"`` installation version accordingly (e.g. ``"~2"``). - - .. code-block:: text +.. code-block:: text - Installation - ============ + Installation + ============ - Step 1: Download the Bundle - --------------------------- + Step 1: Download the Bundle + --------------------------- - Use Composer to add the bundle as a new dependency of your project: + Use Composer to add the bundle as a new dependency of your project: - ```bash - $ composer require "~1" - ``` + ```bash + $ composer require "~1" + ``` - This command requires to have Composer installed globally, as explained - in the [installation chapter](https://getcomposer.org/doc/00-intro.md) - of Composer documentation. + This command requires to have Composer installed globally, as explained + in the [installation chapter](https://getcomposer.org/doc/00-intro.md) + of Composer documentation. - Step 2: Enable the Bundle - ------------------------- + Step 2: Enable the Bundle + ------------------------- - Then, enable the bundle adding the following line in the `AppKernel` - class of your project: + Then, enable the bundle adding the following line in the `AppKernel` + class of your project: - ```php - \\(), - ); - } - ``` + public function registerBundles() + { + $bundles = array( + // ... + return new \\(), + ); + } + ``` - Optionally, you can add *Step 3*, *Step 4*, etc. to explain other required - installation steps, such as registering routes or dumping assets. +This template assumes that your bundle is in its ``1.x`` version. If not, change +the ``"~1"`` installation version accordingly (``"~2"``, ``"~3"``, etc.) +Optionally, you can add more installation steps (*Step 3*, *Step 4*, etc.) to +explain other required installation tasks, such as registering routes or +dumping assets. Routing ------- From 35dddbaab0b5ec9a189256248074c530242cb00c Mon Sep 17 00:00:00 2001 From: Javier Eguiluz Date: Sat, 23 Aug 2014 12:29:14 +0200 Subject: [PATCH 10/11] Reworded a bit the installation instructions --- cookbook/bundles/best_practices.rst | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/cookbook/bundles/best_practices.rst b/cookbook/bundles/best_practices.rst index 7ac545dfc43..97c70987952 100644 --- a/cookbook/bundles/best_practices.rst +++ b/cookbook/bundles/best_practices.rst @@ -208,7 +208,8 @@ following standardized instructions in your ``README.md`` file. Step 1: Download the Bundle --------------------------- - Use Composer to add the bundle as a new dependency of your project: + Open a command console, enter your project directory and execute the + following command to download the latest stable version of this bundle: ```bash $ composer require "~1" From 709707032036af2d0803ede48fbb071b3a9cae4f Mon Sep 17 00:00:00 2001 From: Javier Eguiluz Date: Wed, 27 Aug 2014 16:11:18 +0200 Subject: [PATCH 11/11] Added the fixes suggested by Ryan --- cookbook/bundles/best_practices.rst | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/cookbook/bundles/best_practices.rst b/cookbook/bundles/best_practices.rst index 97c70987952..51465b9d15a 100644 --- a/cookbook/bundles/best_practices.rst +++ b/cookbook/bundles/best_practices.rst @@ -215,15 +215,15 @@ following standardized instructions in your ``README.md`` file. $ composer require "~1" ``` - This command requires to have Composer installed globally, as explained + This command requires you to have Composer installed globally, as explained in the [installation chapter](https://getcomposer.org/doc/00-intro.md) - of Composer documentation. + of the Composer documentation. Step 2: Enable the Bundle ------------------------- - Then, enable the bundle adding the following line in the `AppKernel` - class of your project: + Then, enable the bundle by adding the following line in the `app/AppKernel.php` + file of your project: ```php