Updated the best practices article for reusable bundles #5014

javiereguiluz · 2015-02-19T09:27:48Z

Q	A
Doc fix?	yes
New docs?	no
Applies to	2.3+
Fixed tickets	#3616

wouterj · 2015-02-19T09:28:22Z

cookbook/bundles/best_practices.rst

-suffix.
+A bundle is also a PHP namespace. The namespace must follow the `PSR-0`_ or
+`PSR-4`_ technical interoperability standards for PHP namespaces and class names:
+it starts with a vendor segment, followed by zero or more category segments, and


you should remove the serial comma before "and"

javiereguiluz · 2015-02-19T10:56:06Z

@wouterj thanks for your review. I've fixed everything.

cordoval · 2015-02-19T12:18:38Z

cookbook/bundles/best_practices.rst

-it ends with the namespace short name, which must end with a ``Bundle``
-suffix.
+A bundle is also a PHP namespace. The namespace must follow the `PSR-0`_ or
+`PSR-4`_ technical interoperability standards for PHP namespaces and class names:


do we need the word technical here?

stof · 2015-02-21T10:53:10Z

cookbook/bundles/best_practices.rst

-is used to enforce uniqueness within a bundle (see below for some usage
-examples).
+name using underscores (``acme_blog`` for ``AcmeBlogBundle``). This alias
+is used to enforce uniqueness within a bundle (see below for some usage examples).


it is also used for the bundle configuration in config files

javiereguiluz · 2015-02-21T21:52:50Z

The PR has been updated with all your suggestions.

cordoval · 2015-02-21T22:05:28Z

cookbook/bundles/best_practices.rst

-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 is also a PHP namespace. The namespace must follow the `PSR-0`_ or


bundle has a namespace?

no, bundle is in fact just a namespace or a name to refer to a location on the filesystem

wouterj · 2015-02-22T14:13:17Z

Maybe we should add something about the symfony-bundle Composer package type?

timglabisch · 2015-02-25T22:03:27Z

cookbook/bundles/best_practices.rst


 Directory Structure
 -------------------

-The basic directory structure of a HelloBundle must read as follows:
+The basic directory structure of an AcmeBlogBundle must read as follows (if you
+use `PSR-4`_ the ``Acme/`` and ``BlogBundle/`` folders might not exist):


might not exists could confuse (because the content exists)? any ideas for a better wording here?

xabbuh · 2015-03-03T10:07:57Z

cookbook/bundles/best_practices.rst

+=================================  ========================
+``Acme\Bundle\BlogBundle``         ``AcmeBlogBundle``
+``Acme\BlogBundle``                ``AcmeBlogBundle``
+=================================  ========================


What do you think about shortening the table borders?

stof · 2015-03-03T10:45:17Z

Other best practices for shared bundles IMO:

following semver
being registered on Packagist

wouterj · 2015-05-02T09:46:23Z

cookbook/bundles/best_practices.rst

+              ├─ README.md
+              ├─ Resources/
+              │   ├─ meta/
+              │   │  └─ LICENSE


LICENSE file may also live in the root directory directly (see #4335)

wouterj · 2015-05-02T09:46:35Z

This also fixes #4335

javiereguiluz · 2015-06-23T15:06:53Z

I've implemented all the changes suggested by reviewers and I've rebased it. I hope this PR can be finally ready to be merged. Thanks.

xabbuh · 2015-06-23T17:46:29Z

cookbook/bundles/best_practices.rst

+  can use any other value.
+* ``autoload``, 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.


These two lines need to be indented too to be treated as part of the list item.

xabbuh · 2015-06-23T17:48:53Z

@javiereguiluz There is one minor issue with the list syntax and it seems that the installation instructions for the rst format got lost when rebasing. Besides these two things the PR looks great! 👍

javiereguiluz · 2015-06-24T07:04:44Z

@xabbuh I'm really sorry for having lost some information during the rebase :( I really wish I haven't lost anything else during the rebase. Thanks for your help!

xabbuh · 2015-06-24T14:15:23Z

cookbook/bundles/best_practices.rst

+* ``description``, a brief explanation of the purpose of the bundle;
+* ``type``, use the ``symfony-bundle`` value;
+* ``license``, ``MIT`` is the preferred license for Symfony bundles, but you
+  can use any other value.


should end with a semicolon

by the way, using a definition list rather than an unordered list looks more reasonable to me

I agree. I've reworded it as a definition list. Thanks.

xabbuh · 2015-06-24T14:44:56Z

cookbook/bundles/best_practices.rst

+    name and separates each word with an hyphen. For example: ``AcmeBlogBundle``
+    is transformed into ``blog-bundle`` and ``AcmeSocialConnectBundle`` is
+    transformed into ``social-connect-bundle``.
+``description``


Will it render properly without a blank line between the entries?

I don't know ... so I've added a blank line as suggested. Thanks.

xabbuh · 2015-06-24T15:08:41Z

👍

… (javiereguiluz) This PR was merged into the 2.3 branch. Discussion ---------- Updated the best practices article for reusable bundles | Q | A | ------------- | --- | Doc fix? | yes | New docs? | no | Applies to | 2.3+ | Fixed tickets | #3616 Commits ------- 286631d Added a blank line beteen definition list items 776eaee Reworded as a definition list 4276ced Added back some information wrongly removed during the rebase fa0b902 Fixed a minor syntax issue 9981193 Minor fixes and added a cross link a391563 Updated the best practices article for reusable bundles

weaverryan · 2015-06-26T21:52:22Z

Awesomesauce! Merged with very minor tweaks at sha: e15eb21

wouterj reviewed Feb 19, 2015
View reviewed changes

wouterj added the Status: Needs Work label Feb 19, 2015

cordoval reviewed Feb 19, 2015
View reviewed changes

wouterj added Status: Reviewed and removed Status: Needs Work labels Feb 19, 2015

stof reviewed Feb 21, 2015
View reviewed changes

xabbuh added Status: Needs Work and removed Status: Reviewed labels Feb 21, 2015

cordoval reviewed Feb 21, 2015
View reviewed changes

timglabisch reviewed Feb 25, 2015
View reviewed changes

xabbuh reviewed Mar 3, 2015
View reviewed changes

wouterj reviewed May 2, 2015
View reviewed changes

javiereguiluz added 2 commits June 23, 2015 17:04

Updated the best practices article for reusable bundles

a391563

Minor fixes and added a cross link

9981193

javiereguiluz force-pushed the fix_3616 branch from d8dee69 to 9981193 Compare June 23, 2015 15:05

xabbuh reviewed Jun 23, 2015
View reviewed changes

javiereguiluz added 2 commits June 24, 2015 09:00

Fixed a minor syntax issue

fa0b902

Added back some information wrongly removed during the rebase

4276ced

xabbuh reviewed Jun 24, 2015
View reviewed changes

Reworded as a definition list

776eaee

xabbuh reviewed Jun 24, 2015
View reviewed changes

Added a blank line beteen definition list items

286631d

xabbuh added Status: Reviewed and removed Status: Needs Work labels Jun 24, 2015

weaverryan merged commit 286631d into symfony:2.3 Jun 26, 2015

weaverryan added a commit that referenced this pull request Jun 26, 2015

[#5014] Minor tweaks!

e15eb21

stof mentioned this pull request Aug 4, 2015

[RFC] Change the recommended location for the license file in shared bundles #5599

Closed

javiereguiluz deleted the fix_3616 branch May 24, 2018 15:59

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Updated the best practices article for reusable bundles #5014

Updated the best practices article for reusable bundles #5014

javiereguiluz commented Feb 19, 2015

wouterj Feb 19, 2015

javiereguiluz commented Feb 19, 2015

cordoval Feb 19, 2015

stof Feb 21, 2015

javiereguiluz commented Feb 21, 2015

cordoval Feb 21, 2015

wouterj Feb 21, 2015

wouterj commented Feb 22, 2015

timglabisch Feb 25, 2015

xabbuh Mar 3, 2015

stof commented Mar 3, 2015

wouterj May 2, 2015

wouterj commented May 2, 2015

javiereguiluz commented Jun 23, 2015

xabbuh Jun 23, 2015

xabbuh commented Jun 23, 2015

javiereguiluz commented Jun 24, 2015

xabbuh Jun 24, 2015

xabbuh Jun 24, 2015

javiereguiluz Jun 24, 2015

xabbuh Jun 24, 2015

javiereguiluz Jun 24, 2015

xabbuh commented Jun 24, 2015

weaverryan commented Jun 26, 2015

Updated the best practices article for reusable bundles #5014

Updated the best practices article for reusable bundles #5014

Conversation

javiereguiluz commented Feb 19, 2015

Choose a reason for hiding this comment

javiereguiluz commented Feb 19, 2015

Choose a reason for hiding this comment

Choose a reason for hiding this comment

javiereguiluz commented Feb 21, 2015

Choose a reason for hiding this comment

Choose a reason for hiding this comment

wouterj commented Feb 22, 2015

Choose a reason for hiding this comment

Choose a reason for hiding this comment

stof commented Mar 3, 2015

Choose a reason for hiding this comment

wouterj commented May 2, 2015

javiereguiluz commented Jun 23, 2015

Choose a reason for hiding this comment

xabbuh commented Jun 23, 2015

javiereguiluz commented Jun 24, 2015

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

xabbuh commented Jun 24, 2015

weaverryan commented Jun 26, 2015