First import of the "Official Best Practices" book #4327

javiereguiluz · 2014-10-15T12:59:39Z

As promised, this Pull Request adds the source files of the new "Official Best Practices" book recently published at symfony.com/best-practices.

Similarly to any other Symfony documentation, the community is allowed, and even encouraged, to propose improvements and fixes to this document. However, given the special nature of this document, we'd like to clarify what proposals will be accepted and what proposals will not.

The following will be happily accepted:

Typos and grammar fixes.
Objective errors (errors in code, technical arguments that are irrelevant or wrong, etc.)
Rewordings and simplifications of confusing explanations.
Proposals to add new best practices not covered so far.

The following will not make it:

Complete rewriting of the existing best practices (for instance, a proposal to change "use annotations ..." to "don't use annotations ..." won't be accepted)

Before some of you get mad at us, please let us explain the purpose of this book. The "Official Symfony Best Practices" explains the recommendations that the original creator of Symfony thinks you should follow to develop web applications.

When we talk about opinions instead of facts, it's really hard to tell when someone is wrong. For instance, who of the following developers you think is wrong?

Developer A: you should not use annotations. They may be convenient for this and that, but they have these other problems.
Developer B: you should use annotations. They may have these problems, but it's worth it because of this and that convenience.

For us, both opinions are valid, in the sense that they are not promoting universal truths. It's perfectly fine to think that annotations are good and/or bad.

This is the reason why this book is not about the creator of Symfony thinking that he is smarter than all of us. And this is definitely not the list of perfect practices or mandatory practices. This is just an opinionated list of recommendations by the original creator of Symfony. If you happen to follow them (all or some) that's fine. If you don't want to follow them or even if you think that they are wrong, that's perfectly fine too.

Let us make it clear again: this is not a list of universal truths or mandatory practices. This is just a list of opinions about how to do things. Follow them or not at your will.

If the Symfony community wants to create their own set of "community best practices", that's great! That way, people will have more best practices to choose from and more information to make better decisions.

We really hope things are more clear now. If not, please comment us your concerns and we'll better explain things for you.

Speaking from a strictly technical point of view, I'd like to warn documentation maintainers (@weaverryan, @wouterj and @xabbuh) that I have no idea about the process to follow when adding a new book to the Symfony documentation.

The things that for sure are not going to work right now are the following:

On symfony.com we don't have the CSS style to display the best practices. We'll add it really soon to match the style of the existing PDF file.
On symfony.com the URL http://symfony.com/doc/current/best_practices/index.html now displays a regular web page. Once this book is added to the documentaton pipeline, we'll remove that page to show instead the index of this book.
The PDF generation for this book isn't prepared yet, so we'll have to wait a few days to set everything up.

wouterj · 2014-10-15T13:04:57Z

best_practices/index.rst

+===============================
+
+.. toctree::
+    :hidden:


we don't hide them on the index pages

wouterj · 2014-10-15T13:08:06Z

best_practices/introduction.rst

+
+This guide is **specially suited** for:
+
+* Websites and web applications developed with the full-stack Symfony framework.


I would add "Non decoupled websites and web applications developed with the full-stack Symfony framework" here, since that's where it's about.

wouterj · 2014-10-15T13:13:58Z

best_practises/index.rst needs to be included in a toctree in index.rst.

javiereguiluz · 2014-10-15T13:32:13Z

@wouterj the Travis build is failing because the best-practice directive is missing. I've tried to add it here fabpot/sphinx-php#21 but I don't know either if it's needed nor if it's correctly done.

stof · 2014-10-15T14:00:33Z

@javiereguiluz you need to update the submodule to point to a commit with the new directive included

javiereguiluz · 2014-10-15T14:19:20Z

@stof thanks for pointing me about how to solve this problem. Let's see if Travis is happy now.

…ation

javiereguiluz · 2014-10-15T14:37:09Z

This is the latest message error reported by Travis. Any help is really appreciated:

Exception occurred:
  File "/home/travis/virtualenv/python2.7.8/lib/python2.7/site-packages/sphinx/writers/html.py",
  line 204, in visit_admonition
    node.insert(0, nodes.title(name, admonitionlabels[name]))
KeyError: 'best-practice'
The full traceback has been saved in /tmp/sphinx-err-Tpl_1y.log, if you want to report the
issue to the developers.

stof · 2014-10-15T14:53:40Z

@javiereguiluz try running the build locally to see the full stack trace

javiereguiluz · 2014-10-15T16:25:27Z

@stof thanks again for the advice. I've finally been able to track the error and I've successfully solved it locally. A new PR has been created (fabpot/sphinx-php#22) and once it's merged, I'll try to update the submodule of this repo to see if it works.

henrikbjorn · 2014-10-16T13:09:15Z

IMO "Official" should be changed to "SensioLabs". And then i would not have any objections to the content or recommendations in the book.

"Official: relating to an authority or public body and its activities and responsibilities." and i like to think the public body and authority is the community (even though Fabien have the absolute last say), and the community as a whole have not created these.

ghost · 2014-10-16T13:10:49Z

👍

henrikbjorn · 2014-10-16T13:12:54Z

best_practices/templates.rst

+``::layout.html.twig``                              ``layout.html.twig``
+``AcmeDemoBundle::index.html.twig``                 ``index.html.twig``
+``AcmeDemoBundle:Default:subdir/index.html.twig``   ``default/subdir/index.html.twig``
+``AcmeDemoBundle:Default/subdir:index.html.twig``   ``default/subdir/index.html.twig``


These should use the new notation @AcmeDemo/Default/index.html.twig etc.

We don't think we should use the new notation because all the Symfony documentation, blog posts, talks, etc. use the traditional notation. Therefore, all Symfony developers know the traditional notation and only a small set of developers know the new notation.

javiereguiluz · 2014-10-16T14:22:31Z

@henrikbjorn @krunoknego we think that your proposal is right. We have reworded a paragraph in the introduction. Now these are the "Symfony best practices" instead of the "Official Symfony best practices". We haven't updated the symfony.com/best-practices page because once this book is published, that page will be gone forever.

If the community creates their own set of recommendations, we'll call them "Community Best Practices" or "Symfony Community Best Practices" or something like that.

xabbuh · 2014-10-20T07:44:01Z

@javiereguiluz You can update the submodule reference to point to e58edd22d16cb247267025d557410dcbfa5fa959.

webdevilopers · 2014-10-20T09:09:50Z

👍

javiereguiluz · 2014-10-20T10:57:22Z

thanks @xabbuh! It looks like everything works now as expected.

weaverryan · 2014-10-20T13:12:56Z

Thanks for everyone's feedback! We'll keep moving forward from here :).

@weaverryan

…iereguiluz) This PR was merged into the 2.3 branch. Discussion ---------- First import of the "Official Best Practices" book As promised, this Pull Request adds the source files of the new "Official Best Practices" book recently published at symfony.com/best-practices. Similarly to any other Symfony documentation, the community is allowed, and even encouraged, to propose improvements and fixes to this document. However, given the special nature of this document, we'd like to clarify what proposals will be accepted and what proposals will not. **The following will be happily accepted:** * Typos and grammar fixes. * Objective errors (errors in code, technical arguments that are irrelevant or wrong, etc.) * Rewordings and simplifications of confusing explanations. * Proposals to add new best practices not covered so far. **The following will not make it:** * Complete rewriting of the existing best practices (for instance, a proposal to change *"use annotations ..."* to *"don't use annotations ..."* won't be accepted) Before some of you get mad at us, please let us explain the purpose of this book. The "Official Symfony Best Practices" explains the recommendations that the original creator of Symfony thinks you should follow to develop web applications. When we talk about opinions instead of facts, it's really hard to tell when someone is wrong. For instance, who of the following developers you think is wrong? * *Developer A*: you should not use annotations. They may be convenient for this and that, but they have these other problems. * *Developer B*: you should use annotations. They may have these problems, but it's worth it because of this and that convenience. For us, both opinions are valid, in the sense that they are not promoting universal truths. It's perfectly fine to think that annotations are good and/or bad. This is the reason why this book is not about the creator of Symfony thinking that he is smarter than all of us. And this is definitely not the list of perfect practices or mandatory practices. This is just an opinionated list of recommendations by the original creator of Symfony. If you happen to follow them (all or some) that's fine. If you don't want to follow them or even if you think that they are wrong, that's perfectly fine too. Let us make it clear again: this is not a list of universal truths or mandatory practices. This is just a list of opinions about how to do things. Follow them or not at your will. If the Symfony community wants to create their own set of "community best practices", that's great! That way, people will have more best practices to choose from and more information to make better decisions. We really hope things are more clear now. If not, please comment us your concerns and we'll better explain things for you. ------ Speaking from a strictly technical point of view, I'd like to warn documentation maintainers (@weaverryan, @wouterj and @xabbuh) that I have no idea about the process to follow when adding a new book to the Symfony documentation. The things that for sure are not going to work right now are the following: * On `symfony.com` we don't have the CSS style to display the best practices. We'll add it really soon to match the style of the existing PDF file. * On `symfony.com` the URL `http://symfony.com/doc/current/best_practices/index.html` now displays a regular web page. Once this book is added to the documentaton pipeline, we'll remove that page to show instead the index of this book. * The PDF generation for this book isn't prepared yet, so we'll have to wait a few days to set everything up. Commits ------- 7eb9367 Updated the sphinx submodule to ad support for best-practice directive d001da8 Fixed some typos reported by @henrikbjorn d12cfe5 Renamed "official best practices" to "best practices" af6b70b added the missing "best-practice" directive import in Sphinx configuration 30b9c45 updated fabpot/sphinx-php module reference f100fc0 Added an index directive to the first chapter d317925 Fixed some technical problems as suggested by Wouter 2c2000a first import of the "Official Best Practices" book

first import of the "Official Best Practices" book

2c2000a

wouterj reviewed Oct 15, 2014
View reviewed changes

best_practices/index.rst

===============================

.. toctree::

:hidden:

Copy link

Member

wouterj Oct 15, 2014

Choose a reason for hiding this comment

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

we don't hide them on the index pages

javiereguiluz mentioned this pull request Oct 15, 2014

Symfony Best Practices typos and errors #4321

Closed

wouterj reviewed Oct 15, 2014
View reviewed changes

Fixed some technical problems as suggested by Wouter

d317925

Added an index directive to the first chapter

f100fc0

updated fabpot/sphinx-php module reference

30b9c45

added the missing "best-practice" directive import in Sphinx configur…

af6b70b

…ation

henrikbjorn reviewed Oct 16, 2014
View reviewed changes

Renamed "official best practices" to "best practices"

d12cfe5

Fixed some typos reported by @henrikbjorn

d001da8

Updated the sphinx submodule to ad support for best-practice directive

7eb9367

weaverryan merged commit 7eb9367 into symfony:2.3 Oct 20, 2014

leblanc-simon mentioned this pull request Oct 21, 2014

Best practices Book symfony-fr/symfony-docs-fr#599

Closed

jakzal mentioned this pull request Nov 1, 2014

[DX] Best practices book refer to 2.6, latest installed 2.5.* symfony/symfony#12376

Closed

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

First import of the "Official Best Practices" book #4327

First import of the "Official Best Practices" book #4327

javiereguiluz commented Oct 15, 2014

wouterj Oct 15, 2014

wouterj Oct 15, 2014

cordoval Oct 15, 2014

wouterj commented Oct 15, 2014

javiereguiluz commented Oct 15, 2014

stof commented Oct 15, 2014

javiereguiluz commented Oct 15, 2014

javiereguiluz commented Oct 15, 2014

stof commented Oct 15, 2014

javiereguiluz commented Oct 15, 2014

henrikbjorn commented Oct 16, 2014

ghost commented Oct 16, 2014

henrikbjorn Oct 16, 2014

javiereguiluz Oct 16, 2014

javiereguiluz commented Oct 16, 2014

xabbuh commented Oct 20, 2014

webdevilopers commented Oct 20, 2014

javiereguiluz commented Oct 20, 2014

weaverryan commented Oct 20, 2014


		This guide is specially suited for:

		* Websites and web applications developed with the full-stack Symfony framework.

First import of the "Official Best Practices" book #4327

First import of the "Official Best Practices" book #4327

Conversation

javiereguiluz commented Oct 15, 2014

wouterj Oct 15, 2014

Choose a reason for hiding this comment

wouterj Oct 15, 2014

Choose a reason for hiding this comment

cordoval Oct 15, 2014

Choose a reason for hiding this comment

wouterj commented Oct 15, 2014

javiereguiluz commented Oct 15, 2014

stof commented Oct 15, 2014

javiereguiluz commented Oct 15, 2014

javiereguiluz commented Oct 15, 2014

stof commented Oct 15, 2014

javiereguiluz commented Oct 15, 2014

henrikbjorn commented Oct 16, 2014

ghost commented Oct 16, 2014

henrikbjorn Oct 16, 2014

Choose a reason for hiding this comment

javiereguiluz Oct 16, 2014

Choose a reason for hiding this comment

javiereguiluz commented Oct 16, 2014

xabbuh commented Oct 20, 2014

webdevilopers commented Oct 20, 2014

javiereguiluz commented Oct 20, 2014

weaverryan commented Oct 20, 2014