From d1450343637739eab971a1c42e396f049a440e81 Mon Sep 17 00:00:00 2001 From: Darryl Hein Date: Sat, 5 Nov 2016 16:34:30 -0600 Subject: [PATCH 1/9] Minor changes throughout BP for Reusable Bundles Cleanup and fixes for parts that were difficult to understand --- bundles/best_practices.rst | 38 +++++++++++++++++++------------------- 1 file changed, 19 insertions(+), 19 deletions(-) diff --git a/bundles/best_practices.rst b/bundles/best_practices.rst index 7a371a319b5..7c1507b61ec 100644 --- a/bundles/best_practices.rst +++ b/bundles/best_practices.rst @@ -28,10 +28,11 @@ the guides. Bundle Name ----------- -A bundle is also a PHP namespace. The namespace must follow the `PSR-0`_ or -`PSR-4`_ interoperability standards for PHP namespaces and class names: it starts -with a vendor segment, followed by zero or more category segments, and it ends -with the namespace short name, which must end with a ``Bundle`` suffix. +A bundle name is also a PHP namespace. The namespace must follow the `PSR-0`_ +or `PSR-4`_ interoperability standards for PHP namespaces and class names. +The name starts with the vendor name, followed by zero or more category +segments/names, and it ends with the namespace short name which must end +with ``Bundle``. A namespace becomes a bundle as soon as you add a bundle class to it. The bundle class name must follow these simple rules: @@ -75,7 +76,7 @@ configuration options (see below for some usage examples). Directory Structure ------------------- -The basic directory structure of an AcmeBlogBundle must read as follows: +The basic directory structure of an ``AcmeBlogBundle`` must read as follows: .. code-block:: text @@ -105,15 +106,15 @@ that automated tools can rely on: bundles are published under the MIT license, but you can `choose any license`_; * ``Resources/doc/index.rst``: The root file for the Bundle documentation. -The depth of sub-directories should be kept to the minimum for most used -classes and files (two levels maximum). +The depth of subdirectories should be kept to a minimum for the most used +classes and files. Two levels is the maximum. The bundle directory is read-only. If you need to write temporary files, store them under the ``cache/`` or ``log/`` directory of the host application. Tools can generate files in the bundle directory structure, but only if the generated files are going to be part of the repository. -The following classes and files have specific emplacements (some are mandatory +The following classes and files have specific emplacements (some are mandatory and others are just conventions followed by most developers): =============================== ============================= ================ @@ -138,9 +139,9 @@ Classes ------- The bundle directory structure is used as the namespace hierarchy. For -instance, a ``ContentController`` controller is stored in -``Acme/BlogBundle/Controller/ContentController.php`` and the fully qualified -class name is ``Acme\BlogBundle\Controller\ContentController``. +instance, a ``ContentController`` controller which is stored in +``Acme/BlogBundle/Controller/ContentController.php`` would have the fully +qualified class name of ``Acme\BlogBundle\Controller\ContentController``. All classes and files must follow the :doc:`Symfony coding standards `. @@ -158,8 +159,8 @@ Vendors A bundle must not embed third-party PHP libraries. It should rely on the standard Symfony autoloading instead. -A bundle should not embed third-party libraries written in JavaScript, CSS or -any other language. +A bundle should also not embed third-party libraries written in JavaScript, +CSS or any other language. Tests ----- @@ -185,7 +186,7 @@ All classes and functions must come with full PHPDoc. Extensive documentation should also be provided in the :doc:`reStructuredText ` format, under -the ``Resources/doc/`` directory; the ``Resources/doc/index.rst`` file is +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 @@ -232,7 +233,6 @@ following standardized instructions in your ``README.md`` file. { $bundles = array( // ... - new \\(), ); @@ -391,8 +391,8 @@ The ``composer.json`` file should include at least the following metadata: ``name`` Consists of the vendor and the short bundle name. If you are releasing the bundle on your own instead of on behalf of a company, use your personal name - (e.g. ``johnsmith/blog-bundle``). The bundle short name excludes the vendor - name and separates each word with an hyphen. For example: ``AcmeBlogBundle`` + (e.g. ``johnsmith/blog-bundle``). Exclude the vendor name from the bundle + short name and separate each word with an hyphen. For example: ``AcmeBlogBundle`` is transformed into ``blog-bundle`` and ``AcmeSocialConnectBundle`` is transformed into ``social-connect-bundle``. @@ -404,10 +404,10 @@ The ``composer.json`` file should include at least the following metadata: ``license`` ``MIT`` is the preferred license for Symfony bundles, but you can use any - other license. + license. ``autoload`` - This information is used by Symfony to load the classes of the bundle. The + This information is used by Symfony to load the classes in the bundle. The `PSR-4`_ autoload standard is recommended for modern bundles, but `PSR-0`_ standard is also supported. From f749f0d551de9d8cf49197987efd143b45d55b53 Mon Sep 17 00:00:00 2001 From: Darryl Hein Date: Tue, 8 Nov 2016 16:35:29 -0700 Subject: [PATCH 2/9] Removing trailing space --- bundles/best_practices.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/bundles/best_practices.rst b/bundles/best_practices.rst index 7c1507b61ec..2d22e4958e9 100644 --- a/bundles/best_practices.rst +++ b/bundles/best_practices.rst @@ -114,7 +114,7 @@ them under the ``cache/`` or ``log/`` directory of the host application. Tools can generate files in the bundle directory structure, but only if the generated files are going to be part of the repository. -The following classes and files have specific emplacements (some are mandatory +The following classes and files have specific emplacements (some are mandatory and others are just conventions followed by most developers): =============================== ============================= ================ From 16d5d39b194999189d26b49506c4098d54365675 Mon Sep 17 00:00:00 2001 From: Darryl Hein Date: Tue, 8 Nov 2016 16:39:20 -0700 Subject: [PATCH 3/9] Reverting previous grammar change --- bundles/best_practices.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/bundles/best_practices.rst b/bundles/best_practices.rst index 2d22e4958e9..b1b4ea4d7f2 100644 --- a/bundles/best_practices.rst +++ b/bundles/best_practices.rst @@ -407,7 +407,7 @@ The ``composer.json`` file should include at least the following metadata: license. ``autoload`` - This information is used by Symfony to load the classes in the bundle. The + This information is used by Symfony to load the classes of the bundle. The `PSR-4`_ autoload standard is recommended for modern bundles, but `PSR-0`_ standard is also supported. From 592b9d22b0514539a1e733365d89186311fec264 Mon Sep 17 00:00:00 2001 From: Darryl Hein Date: Wed, 16 Nov 2016 10:14:48 -0700 Subject: [PATCH 4/9] reword the documentation section re Resources/doc Trying to implement comments made on pull request. --- bundles/best_practices.rst | 10 ++++++---- 1 file changed, 6 insertions(+), 4 deletions(-) diff --git a/bundles/best_practices.rst b/bundles/best_practices.rst index b1b4ea4d7f2..bcb1b9dd473 100644 --- a/bundles/best_practices.rst +++ b/bundles/best_practices.rst @@ -184,10 +184,12 @@ Documentation All classes and functions must come with full PHPDoc. -Extensive documentation should also be provided in the -:doc:`reStructuredText ` format, under -the ``Resources/doc/`` directory. The ``Resources/doc/index.rst`` file is -the only mandatory file and must be the entry point for the documentation. +Extensive documentation should also be provided in the ``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 +point for the documentation. The +:doc:`reStructuredText (rST) ` is the most +common format as it's what's used to render the documentation on symfony.com Installation Instructions ~~~~~~~~~~~~~~~~~~~~~~~~~ From 99dc9a96cb96c7e264d951ddcb103694ef80ba9b Mon Sep 17 00:00:00 2001 From: Darryl Hein Date: Wed, 16 Nov 2016 10:17:27 -0700 Subject: [PATCH 5/9] add mention of symfony.com re folder structure --- bundles/best_practices.rst | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/bundles/best_practices.rst b/bundles/best_practices.rst index bcb1b9dd473..6d3fcc94f45 100644 --- a/bundles/best_practices.rst +++ b/bundles/best_practices.rst @@ -185,7 +185,8 @@ Documentation All classes and functions must come with full PHPDoc. Extensive documentation should also be provided in the ``Resources/doc/`` -directory. The index file (for example ``Resources/doc/index.rst`` or +directory (though only required when the documentation is shown on symfony.com). +The index file (for example ``Resources/doc/index.rst`` or ``Resources/doc/index.md``) is the only mandatory file and must be the entry point for the documentation. The :doc:`reStructuredText (rST) ` is the most From ae29ce8f068b105f32bf3e59b1c94af5f27317d3 Mon Sep 17 00:00:00 2001 From: Javier Eguiluz Date: Tue, 14 Feb 2017 16:38:08 +0100 Subject: [PATCH 6/9] Removed backticks from bundle names --- bundles/best_practices.rst | 15 +++++++-------- 1 file changed, 7 insertions(+), 8 deletions(-) diff --git a/bundles/best_practices.rst b/bundles/best_practices.rst index 6d3fcc94f45..640a0030620 100644 --- a/bundles/best_practices.rst +++ b/bundles/best_practices.rst @@ -49,8 +49,8 @@ Here are some valid bundle namespaces and class names: ========================== ================== Namespace Bundle Class Name ========================== ================== -``Acme\Bundle\BlogBundle`` ``AcmeBlogBundle`` -``Acme\BlogBundle`` ``AcmeBlogBundle`` +``Acme\Bundle\BlogBundle`` AcmeBlogBundle +``Acme\BlogBundle`` AcmeBlogBundle ========================== ================== By convention, the ``getName()`` method of the bundle class should return the @@ -59,8 +59,7 @@ class name. .. note:: If you share your bundle publicly, you must use the bundle class name as - the name of the repository (``AcmeBlogBundle`` and not ``BlogBundle`` - for instance). + the name of the repository (AcmeBlogBundle and not BlogBundle for instance). .. note:: @@ -69,14 +68,14 @@ class name. :class:`Symfony\\Bundle\\FrameworkBundle\\FrameworkBundle`. Each bundle has an alias, which is the lower-cased short version of the bundle -name using underscores (``acme_blog`` for ``AcmeBlogBundle``). This alias +name using underscores (``acme_blog`` for AcmeBlogBundle). This alias is used to enforce uniqueness within a project and for defining bundle's configuration options (see below for some usage examples). Directory Structure ------------------- -The basic directory structure of an ``AcmeBlogBundle`` must read as follows: +The basic directory structure of an AcmeBlogBundle must read as follows: .. code-block:: text @@ -395,8 +394,8 @@ The ``composer.json`` file should include at least the following metadata: Consists of the vendor and the short bundle name. If you are releasing the bundle on your own instead of on behalf of a company, use your personal name (e.g. ``johnsmith/blog-bundle``). Exclude the vendor name from the bundle - short name and separate each word with an hyphen. For example: ``AcmeBlogBundle`` - is transformed into ``blog-bundle`` and ``AcmeSocialConnectBundle`` is + short name and separate each word with an hyphen. For example: AcmeBlogBundle + is transformed into ``blog-bundle`` and AcmeSocialConnectBundle is transformed into ``social-connect-bundle``. ``description`` From 07dd2601a18a22098c3330f02fb39c6ccc44630c Mon Sep 17 00:00:00 2001 From: Javier Eguiluz Date: Tue, 14 Feb 2017 16:41:26 +0100 Subject: [PATCH 7/9] Reverted the changes about bundle namespaces --- bundles/best_practices.rst | 9 ++++----- 1 file changed, 4 insertions(+), 5 deletions(-) diff --git a/bundles/best_practices.rst b/bundles/best_practices.rst index 640a0030620..e9e1a9198f1 100644 --- a/bundles/best_practices.rst +++ b/bundles/best_practices.rst @@ -28,11 +28,10 @@ the guides. Bundle Name ----------- -A bundle name is also a PHP namespace. The namespace must follow the `PSR-0`_ -or `PSR-4`_ interoperability standards for PHP namespaces and class names. -The name starts with the vendor name, followed by zero or more category -segments/names, and it ends with the namespace short name which must end -with ``Bundle``. +A bundle is also a PHP namespace. The namespace must follow the `PSR-0`_ or +`PSR-4`_ interoperability standards for PHP namespaces and class names: it starts +with a vendor segment, followed by zero or more category segments, and it ends +with the namespace short name, which must end with ``Bundle``. A namespace becomes a bundle as soon as you add a bundle class to it. The bundle class name must follow these simple rules: From 73d2d7cef93e3a268b641b76d0d8df1d8caa8057 Mon Sep 17 00:00:00 2001 From: Javier Eguiluz Date: Tue, 14 Feb 2017 16:44:53 +0100 Subject: [PATCH 8/9] Better explain the purpose of the "license" Composer metadata --- bundles/best_practices.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/bundles/best_practices.rst b/bundles/best_practices.rst index e9e1a9198f1..2eabf7e95ed 100644 --- a/bundles/best_practices.rst +++ b/bundles/best_practices.rst @@ -404,8 +404,7 @@ The ``composer.json`` file should include at least the following metadata: Use the ``symfony-bundle`` value. ``license`` - ``MIT`` is the preferred license for Symfony bundles, but you can use any - license. + a string (or array of strings) with a `valid license identifier`_, such as ``MIT``. ``autoload`` This information is used by Symfony to load the classes of the bundle. The @@ -426,3 +425,4 @@ Learn more .. _`Semantic Versioning Standard`: http://semver.org/ .. _`Packagist`: https://packagist.org/ .. _`choose any license`: http://choosealicense.com/ +.. _`valid license identifier`: https://spdx.org/licenses/ From 5cbb6e851faf1cf5b20d1d60f744869dd6d75bfc Mon Sep 17 00:00:00 2001 From: Jules Pietri Date: Sat, 29 Jul 2017 13:41:48 +0200 Subject: [PATCH 9/9] Update best_practices.rst --- 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 2eabf7e95ed..9d090708b67 100644 --- a/bundles/best_practices.rst +++ b/bundles/best_practices.rst @@ -183,12 +183,12 @@ Documentation All classes and functions must come with full PHPDoc. Extensive documentation should also be provided in the ``Resources/doc/`` -directory (though only required when the documentation is shown on symfony.com). +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 point for the documentation. The -:doc:`reStructuredText (rST) ` is the most -common format as it's what's used to render the documentation on symfony.com +:doc:`reStructuredText (rST) ` is the format +used to render the documentation on symfony.com. Installation Instructions ~~~~~~~~~~~~~~~~~~~~~~~~~