From 88884feff96a3caaa14c25d3e64dc258439745b1 Mon Sep 17 00:00:00 2001 From: Vladimir Sadicov Date: Thu, 3 Jan 2019 00:00:56 +0200 Subject: [PATCH 1/6] initial changes to present new bundle directory structure --- bundles/best_practices.rst | 44 ++++++++++++++++++++------------------ 1 file changed, 23 insertions(+), 21 deletions(-) diff --git a/bundles/best_practices.rst b/bundles/best_practices.rst index 6424d807b5a..b2507233930 100644 --- a/bundles/best_practices.rst +++ b/bundles/best_practices.rst @@ -68,30 +68,32 @@ The basic directory structure of an AcmeBlogBundle must read as follows: .. code-block:: text / - ├─ AcmeBlogBundle.php - ├─ Controller/ + ├─ config/ + ├─ src/ + | ├─ AcmeBlogBundle.php + | ├─ Controller/ + | ├─ Resources/ + | | ├─ config/ + | | ├─ doc/ + │ | | └─ index.rst + │ | ├─ translations/ + │ | ├─ views/ + │ | └─ public/ + ├─ tests/ ├─ README.md - ├─ LICENSE - ├─ Resources/ - │ ├─ config/ - │ ├─ doc/ - │ │ └─ index.rst - │ ├─ translations/ - │ ├─ views/ - │ └─ public/ - └─ Tests/ + └─ LICENSE **The following files are mandatory**, because they ensure a structure convention that automated tools can rely on: -* ``AcmeBlogBundle.php``: This is the class that transforms a plain directory +* ``src/AcmeBlogBundle.php``: This is the class that transforms a plain directory into a Symfony bundle (change this to your bundle's name); * ``README.md``: This file contains the basic description of the bundle and it usually shows some basic examples and links to its full documentation (it can use any of the markup formats supported by GitHub, such as ``README.rst``); * ``LICENSE``: The full contents of the license used by the code. Most third-party bundles are published under the MIT license, but you can `choose any license`_; -* ``Resources/doc/index.rst``: The root file for the Bundle documentation. +* ``src/Resources/doc/index.rst``: The root file for the Bundle documentation. The depth of subdirectories should be kept to a minimum for the most used classes and files. Two levels is the maximum. @@ -107,19 +109,19 @@ and others are just conventions followed by most developers): =================================================== ======================================== Type Directory =================================================== ======================================== -Commands ``Command/`` -Controllers ``Controller/`` -Service Container Extensions ``DependencyInjection/`` -Doctrine ORM entities (when not using annotations) ``Entity/`` -Doctrine ODM documents (when not using annotations) ``Document/`` -Event Listeners ``EventListener/`` -Configuration (routes, services, etc.) ``Resources/config/`` +Commands ``src/Command/`` +Controllers ``src/Controller/`` +Service Container Extensions ``src/DependencyInjection/`` +Doctrine ORM entities (when not using annotations) ``src/Entity/`` +Doctrine ODM documents (when not using annotations) ``src/Document/`` +Event Listeners ``src/EventListener/`` +Configuration (routes, services, etc.) ``config/`` Web Assets (CSS, JS, images) ``Resources/public/`` Translation files ``Resources/translations/`` Validation (when not using annotations) ``Resources/config/validation/`` Serialization (when not using annotations) ``Resources/config/serialization/`` Templates ``Resources/views/`` -Unit and Functional Tests ``Tests/`` +Unit and Functional Tests ``tests/`` =================================================== ======================================== Classes From a41e097d6e9326f2d0d9386de7c02c98f9e29ba0 Mon Sep 17 00:00:00 2001 From: Vladimir Sadicov Date: Thu, 3 Jan 2019 00:06:19 +0200 Subject: [PATCH 2/6] fix missed src/ mention --- bundles/best_practices.rst | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/bundles/best_practices.rst b/bundles/best_practices.rst index b2507233930..c0720325fd5 100644 --- a/bundles/best_practices.rst +++ b/bundles/best_practices.rst @@ -116,11 +116,11 @@ Doctrine ORM entities (when not using annotations) ``src/Entity/`` Doctrine ODM documents (when not using annotations) ``src/Document/`` Event Listeners ``src/EventListener/`` Configuration (routes, services, etc.) ``config/`` -Web Assets (CSS, JS, images) ``Resources/public/`` -Translation files ``Resources/translations/`` -Validation (when not using annotations) ``Resources/config/validation/`` -Serialization (when not using annotations) ``Resources/config/serialization/`` -Templates ``Resources/views/`` +Web Assets (CSS, JS, images) ``src/Resources/public/`` +Translation files ``src/Resources/translations/`` +Validation (when not using annotations) ``src/Resources/config/validation/`` +Serialization (when not using annotations) ``src/Resources/config/serialization/`` +Templates ``src/Resources/views/`` Unit and Functional Tests ``tests/`` =================================================== ======================================== From 17f7e93f391e381c882925861c845637e14a96fe Mon Sep 17 00:00:00 2001 From: Vladimir Sadicov Date: Thu, 3 Jan 2019 16:05:12 +0200 Subject: [PATCH 3/6] return config/ directory to resources --- bundles/best_practices.rst | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/bundles/best_practices.rst b/bundles/best_practices.rst index c0720325fd5..5a16c700138 100644 --- a/bundles/best_practices.rst +++ b/bundles/best_practices.rst @@ -68,7 +68,6 @@ The basic directory structure of an AcmeBlogBundle must read as follows: .. code-block:: text / - ├─ config/ ├─ src/ | ├─ AcmeBlogBundle.php | ├─ Controller/ @@ -115,7 +114,7 @@ Service Container Extensions ``src/DependencyInjection/` Doctrine ORM entities (when not using annotations) ``src/Entity/`` Doctrine ODM documents (when not using annotations) ``src/Document/`` Event Listeners ``src/EventListener/`` -Configuration (routes, services, etc.) ``config/`` +Configuration (routes, services, etc.) ``src/Resources/config/`` Web Assets (CSS, JS, images) ``src/Resources/public/`` Translation files ``src/Resources/translations/`` Validation (when not using annotations) ``src/Resources/config/validation/`` From a8fc678c15b780059c258c090e813d7cde7defa3 Mon Sep 17 00:00:00 2001 From: Vladimir Sadicov Date: Thu, 3 Jan 2019 17:57:26 +0200 Subject: [PATCH 4/6] tweaked directories mentioned in document --- bundles/best_practices.rst | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/bundles/best_practices.rst b/bundles/best_practices.rst index 5a16c700138..49e7387e31f 100644 --- a/bundles/best_practices.rst +++ b/bundles/best_practices.rst @@ -154,7 +154,7 @@ Tests ----- A bundle should come with a test suite written with PHPUnit and stored under -the ``Tests/`` directory. Tests should follow the following principles: +the ``tests/`` directory. Tests should follow the following principles: * The test suite must be executable with a simple ``phpunit`` command run from a sample application; @@ -258,10 +258,10 @@ Documentation All classes and functions must come with full PHPDoc. -Extensive documentation should also be provided in the ``Resources/doc/`` +Extensive documentation should also be provided in the ``src/Resources/doc/`` directory. -The index file (for example ``Resources/doc/index.rst`` or -``Resources/doc/index.md``) is the only mandatory file and must be the entry +The index file (for example ``src/Resources/doc/index.rst`` or +``src/Resources/doc/index.md``) is the only mandatory file and must be the entry point for the documentation. The :doc:`reStructuredText (rST) ` is the format used to render the documentation on symfony.com. @@ -539,7 +539,7 @@ lets you override any resource/file of any bundle. See :ref:`http-kernel-resourc for more details about transforming physical paths into logical paths. Beware that templates use a simplified version of the logical path shown above. -For example, an ``index.html.twig`` template located in the ``Resources/views/Default/`` +For example, an ``index.html.twig`` template located in the ``src/Resources/views/Default/`` directory of the FooBundle, is referenced as ``@Foo/Default/index.html.twig``. Learn more From 461be35c6781530fc169c50e56baea280c181069 Mon Sep 17 00:00:00 2001 From: Vladimir Sadicov Date: Fri, 4 Jan 2019 22:34:59 +0200 Subject: [PATCH 5/6] doc -> docs, move docs to root folder, tweak files order --- bundles/best_practices.rst | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/bundles/best_practices.rst b/bundles/best_practices.rst index 49e7387e31f..ecf6aab4395 100644 --- a/bundles/best_practices.rst +++ b/bundles/best_practices.rst @@ -68,16 +68,16 @@ The basic directory structure of an AcmeBlogBundle must read as follows: .. code-block:: text / + ├─ docs/ + │ └─ index.rst ├─ src/ - | ├─ AcmeBlogBundle.php | ├─ Controller/ | ├─ Resources/ | | ├─ config/ - | | ├─ doc/ - │ | | └─ index.rst │ | ├─ translations/ │ | ├─ views/ │ | └─ public/ + | └─ AcmeBlogBundle.php ├─ tests/ ├─ README.md └─ LICENSE From 58a9a56b00aaea7b30c1be1ca0635daf74b800d9 Mon Sep 17 00:00:00 2001 From: Vladimir Sadicov Date: Fri, 4 Jan 2019 22:40:02 +0200 Subject: [PATCH 6/6] tweak documentation paths --- bundles/best_practices.rst | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/bundles/best_practices.rst b/bundles/best_practices.rst index ecf6aab4395..8e024c1294d 100644 --- a/bundles/best_practices.rst +++ b/bundles/best_practices.rst @@ -92,7 +92,7 @@ that automated tools can rely on: can use any of the markup formats supported by GitHub, such as ``README.rst``); * ``LICENSE``: The full contents of the license used by the code. Most third-party bundles are published under the MIT license, but you can `choose any license`_; -* ``src/Resources/doc/index.rst``: The root file for the Bundle documentation. +* ``docs/index.rst``: The root file for the Bundle documentation. The depth of subdirectories should be kept to a minimum for the most used classes and files. Two levels is the maximum. @@ -258,10 +258,10 @@ Documentation All classes and functions must come with full PHPDoc. -Extensive documentation should also be provided in the ``src/Resources/doc/`` +Extensive documentation should also be provided in the ``docs/`` directory. -The index file (for example ``src/Resources/doc/index.rst`` or -``src/Resources/doc/index.md``) is the only mandatory file and must be the entry +The index file (for example ``docs/index.rst`` or +``docs/index.md``) is the only mandatory file and must be the entry point for the documentation. The :doc:`reStructuredText (rST) ` is the format used to render the documentation on symfony.com.