Skip to content

Minor changes throughout Best Practices for Reusable Bundles #7118

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Closed
wants to merge 9 commits into from
Closed

Minor changes throughout Best Practices for Reusable Bundles #7118

Changes from 8 commits
Commits
Show all changes
9 commits
Select commit Hold shift + click to select a range
d145034
Minor changes throughout BP for Reusable Bundles
darrylhein Nov 5, 2016
f749f0d
Removing trailing space
darrylhein Nov 8, 2016
16d5d39
Reverting previous grammar change
darrylhein Nov 8, 2016
592b9d2
reword the documentation section re Resources/doc
darrylhein Nov 16, 2016
99dc9a9
add mention of symfony.com re folder structure
darrylhein Nov 16, 2016
ae29ce8
Removed backticks from bundle names
javiereguiluz Feb 14, 2017
07dd260
Reverted the changes about bundle namespaces
javiereguiluz Feb 14, 2017
73d2d7c
Better explain the purpose of the "license" Composer metadata
javiereguiluz Feb 14, 2017
5cbb6e8
Update best_practices.rst
HeahDude Jul 29, 2017
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
47 changes: 24 additions & 23 deletions bundles/best_practices.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -31,7 +31,7 @@ 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.
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:
Expand All @@ -48,8 +48,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
Expand All @@ -58,8 +58,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::

Expand All @@ -68,7 +67,7 @@ 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).

Expand Down Expand Up @@ -105,8 +104,8 @@ 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
Expand Down Expand Up @@ -138,9 +137,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 </contributing/code/standards>`.

Expand All @@ -158,8 +157,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
-----
Expand All @@ -183,10 +182,13 @@ Documentation

All classes and functions must come with full PHPDoc.

Extensive documentation should also be provided in the
:doc:`reStructuredText </contributing/documentation/format>` 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 (though only required when the documentation is shown on symfony.com).
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

the sentence in braces looks wrong to me. Providing doc is required when sharing your bundle. the sentence looks like doc is required only when showing it on symfony.com

Putting it inside Resources/doc/ and using rST is what is required when rendering it on symfony.com.
when rendering the doc elsewhere, we could live with the doc being elsewhere (in a docs folder at the root of the repo for instance, which is a convention supported by github pages now) and in any format (as long as you provide a version readable by humans somewhere, and link to it)

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) </contributing/documentation/format>` is the most
common format as it's what's used to render the documentation on symfony.com
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

most common is wrong here. Most bundles don't have their doc on symfony.com.

If we were running stats over all bundles, I'm quite sure markdown would be the most common one...


Installation Instructions
~~~~~~~~~~~~~~~~~~~~~~~~~
Expand Down Expand Up @@ -232,7 +234,6 @@ following standardized instructions in your ``README.md`` file.
{
$bundles = array(
// ...

new <vendor>\<bundle-name>\<bundle-long-name>(),
);

Expand Down Expand Up @@ -391,9 +392,9 @@ 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``
is transformed into ``blog-bundle`` and ``AcmeSocialConnectBundle`` is
(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``.

``description``
Expand All @@ -403,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
other 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
Expand All @@ -425,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/