first import of the "Official Best Practices" book
Fixed some technical problems as suggested by Wouter
Added an index directive to the first chapter
updated fabpot/sphinx-php module reference
added the missing "best-practice" directive import in Sphinx configuration
Renamed "official best practices" to "best practices"
Fixed some typos reported by @henrikbjorn
[Forms] add missing features being new in 2.3

These features are:

* Use the submit() (instead of bind()) method to manually submit a
  form.
* The ability to change a form's action and method.
outline implications of the kernel.terminate event
feature #4085 [Component][Forms] add missing features introduced in 2.3 (xabbuh)

This PR was merged into the 2.3 branch.

Discussion
----------

[Component][Forms] add missing features introduced in 2.3

| Q             | A
| ------------- | ---
| Doc fix?      | no
| New docs?     | yes (symfony/symfony#6522)
| Applies to    | all
| Fixed tickets | #2969

- [x] use ``submit()`` instead of ``bind()`` to manually submit a form
- [x] configure method and action of a form
- [ ] ~~render a form's start and its end separately~~ (see [the comment](https://github.com/symfony/symfony-docs/pull/4085#issuecomment-52386947))
- [ ] configure buttons

Commits
-------

33f6422 [Forms] add missing features being new in 2.3
feature #4224 [Components][HttpKernel] outline implications of the kernel.terminate event (xabbuh)

This PR was merged into the 2.3 branch.

Discussion
----------

[Components][HttpKernel] outline implications of the kernel.terminate event

| Q             | A
| ------------- | ---
| Doc fix?      | yes
| New docs?     | no
| Applies to    | all
| Fixed tickets | #4198

Commits
-------

c4f4588 outline implications of the kernel.terminate event
Updated the sphinx submodule to ad support for best-practice directive
Correct capitalization for the Content-Type header
minor #4345 Correct capitalization for the Content-Type header (GeertDD)

This PR was submitted for the master branch but it was merged into the 2.3 branch instead (closes #4345).

Discussion
----------

Correct capitalization for the Content-Type header

http://tools.ietf.org/html/rfc7231#section-3.1.1.5

Commits
-------

74dc6f8 Correct capitalization for the Content-Type header
feature #4327 First import of the "Official Best Practices" book (javiereguiluz)

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
Merge branch '2.3' into 2.5

* 2.3:
  Correct capitalization for the Content-Type header
  Updated the sphinx submodule to ad support for best-practice directive
  outline implications of the kernel.terminate event
  [Forms] add missing features being new in 2.3
  Fixed some typos reported by @henrikbjorn
  Renamed "official best practices" to "best practices"
  added the missing "best-practice" directive import in Sphinx configuration
  updated fabpot/sphinx-php module reference
  Added an index directive to the first chapter
  Fixed some technical problems as suggested by Wouter
  first import of the "Official Best Practices" book
Merge branch '2.5'

* 2.5:
  Correct capitalization for the Content-Type header
  Updated the sphinx submodule to ad support for best-practice directive
  outline implications of the kernel.terminate event
  [Forms] add missing features being new in 2.3
  Fixed some typos reported by @henrikbjorn
  Renamed "official best practices" to "best practices"
  added the missing "best-practice" directive import in Sphinx configuration
  updated fabpot/sphinx-php module reference
  Added an index directive to the first chapter
  Fixed some technical problems as suggested by Wouter
  first import of the "Official Best Practices" book