Merge symfony/master into beberlei/master

Author: beberlei

contributing/code/bugs.rst

@@ -1,19 +1,20 @@
 Reporting a Bug
 ===============
 
-Whenever you find a bug in Symfony, we kindly ask you to report it. It helps
-us make a better Symfony.
+Whenever you find a bug in Symfony2, we kindly ask you to report it. It helps
+us make a better Symfony2.
 
 .. caution::
-   If you think you've found a security issue, please use the special
-   doc:`procedure <security>` instead.
+
+    If you think you've found a security issue, please use the special
+    :doc:`procedure <security>` instead.
 
 Before submitting a bug:
 
  * Double-check the official `documentation`_ to see if you're not misusing the
    framework;
 
- * Ask assistance on the `users mailing-list`_, the `forum`, or on the
+ * Ask assistance on the `users mailing-list`_, the `forum`_, or on the
    #symfony `IRC channel`_ if you're not sure if your issue is really a bug.
 
 If your problem definitely looks like a bug, report it using the official bug

contributing/code/conventions.rst

@@ -0,0 +1,58 @@
+Conventions
+===========
+
+The :doc:`standards` document describes the coding standards for the Symfony2
+projects and the internal and third-party bundles. This document describes
+coding standards and conventions used in the core framework to make it more
+consistent and predictable. You can follow them in your own code, but you
+don't need to.
+
+Method Names
+------------
+
+When an object has a "main" many relation with related "things"
+(objects, parameters, ...), the method names are normalized:
+
+  * ``get()``
+  * ``set()``
+  * ``has()``
+  * ``all()``
+  * ``replace()``
+  * ``remove()``
+  * ``clear()``
+  * ``isEmpty()``
+  * ``add()``
+  * ``register()``
+  * ``count()``
+  * ``keys()``
+
+The usage of these methods are only allowed when it is clear that there
+is a main relation:
+
+* a ``CookieJar`` has many ``Cookie``s;
+
+* a Service ``Container`` has many services and many parameters (as services
+  is the main relation, we use the naming convention for this relation);
+
+* a Console ``Input`` has many arguments and many options. There is no "main"
+  relation, and so the naming convention does not apply.
+
+For many relations where the convention does not apply, the following methods
+must be used instead (where ``XXX`` is the name of the related thing):
+
+============== =================
+Main Relation  Other Relations
+============== =================
+``get()``      ``getXXX()``
+``set()``      ``setXXX()``
+``has()``      ``hasXXX()``
+``all()``      ``getXXXs()``
+``replace()``  ``setXXXs()``
+``remove()``   ``removeXXX()``
+``clear()``    ``clearXXX()``
+``isEmpty()``  ``isEmptyXXX()``
+``add()``      ``addXXX()``
+``register()`` ``registerXXX()``
+``count()``    ``countXXX()``
+``keys()``     n/a
+============== =================

contributing/code/index.rst

@@ -7,6 +7,7 @@ Contributing Code
     bugs
     patches
     security
-    standards
     tests
+    standards
+    conventions
     license

contributing/code/license.rst

@@ -5,11 +5,11 @@ Symfony2 is released under the MIT license.
 
 According to `Wikipedia`_:
 
-  "It is a permissive license, meaning that it permits reuse within
-  proprietary software on the condition that the license is distributed with
-  that software. The license is also GPL-compatible, meaning that the GPL
-  permits combination and redistribution with software that uses the MIT
-  License."
+    "It is a permissive license, meaning that it permits reuse within
+    proprietary software on the condition that the license is distributed with
+    that software. The license is also GPL-compatible, meaning that the GPL
+    permits combination and redistribution with software that uses the MIT
+    License."
 
 The License
 -----------

contributing/code/patches.rst

@@ -2,7 +2,7 @@ Submitting a Patch
 ==================
 
 Patches are the best way to provide a bug fix or to propose enhancements to
-Symfony.
+Symfony2.
 
 Initial Setup
 -------------
@@ -24,8 +24,9 @@ Set up your user information with your real name and a working email address:
     $ git config --global user.email you@example.com
 
 .. tip::
-   If you are new to Git, we highly recommend you to read the excellent and free
-   `ProGit`_ book.
+
+    If you are new to Git, we highly recommend you to read the excellent and
+    free `ProGit`_ book.
 
 Get the Symfony2 code source:
 
@@ -61,11 +62,12 @@ topic branch:
     $ git checkout -b BRANCH_NAME
 
 .. tip::
-   Use a descriptive name for your branch (`ticket_XXX` where `XXX` is the ticket
-   number is a good convention for bug fixes).
+
+    Use a descriptive name for your branch (`ticket_XXX` where `XXX` is the
+    ticket number is a good convention for bug fixes).
 
 The above command automatically switches the code to the newly created branch
-(check the branch you are working on with `git branch`.)
+(check the branch you are working on with `git branch`).
 
 Work on the code as much as you want and commit as much as you want; but keep
 in mind the following:
@@ -82,11 +84,13 @@ in mind the following:
 * Write good commit messages.
 
 .. tip::
-   A good commit message is composed of a summary (the first line), optionally
-   followed by a blank line and a more detailed description. The summary should
-   start with the Component you are working on in square brackets
-   (`[DependencyInjection]`, `[FrameworkBundle]`, ...). Use a verb (`fixed ...`,
-   `added ...`, ...) to start the summary and don't add a period at the end.
+
+    A good commit message is composed of a summary (the first line), optionally
+    followed by a blank line and a more detailed description. The summary
+    should start with the Component you are working on in square brackets
+    (`[DependencyInjection]`, `[FrameworkBundle]`, ...). Use a verb
+    (`fixed ...`, `added ...`, ...) to start the summary and don't add a period
+    at the end.
 
 Submitting a Patch
 ------------------

contributing/code/security.rst

@@ -1,7 +1,7 @@
 Reporting a Security Issue
 ==========================
 
-Found a security issue in Symfony? Don't use the mailing-list or the bug
+Found a security issue in Symfony2? Don't use the mailing-list or the bug
 tracker. All security issues must be sent to **security [at]
 symfony-project.com** instead. Emails sent to this address are forwarded to
 the Symfony core-team private mailing-list.
@@ -17,4 +17,5 @@ confirmed, the core-team works on a solution following these steps:
 5. Publish the post on the official Symfony blog.
 
 .. note::
-   While we are working on a patch, please do not reveal the issue publicly.
+
+    While we are working on a patch, please do not reveal the issue publicly.

contributing/code/standards.rst

@@ -1,9 +1,9 @@
 Coding Standards
 ================
 
-When contributing code to Symfony, you must follow its coding standards. To
+When contributing code to Symfony2, you must follow its coding standards. To
 make a long story short, here is the golden rule: *Imitate the existing
-Symfony code*.
+Symfony2 code*.
 
 Structure
 ---------

contributing/code/tests.rst

@@ -28,8 +28,6 @@ The test suite need the following third-party libraries:
 
 * Doctrine
 * Doctrine Migrations
-* Phing
-* Propel
 * Swiftmailer
 * Twig
 * Zend Framework
@@ -41,7 +39,8 @@ To install them all, run the `install_vendors.sh` script:
     $ sh install_vendors.sh
 
 .. note::
-   Note that the script takes some time to finish.
+
+    Note that the script takes some time to finish.
 
 After installation, you can update the vendors anytime with the
 `update_vendors.sh` script:
@@ -66,8 +65,9 @@ The output should display `OK`. If not, you need to figure out what's going on
 and if the tests are broken because of your modifications.
 
 .. tip::
-   Run the test suite before applying your modifications to check that they run
-   fine on your configuration.
+
+    Run the test suite before applying your modifications to check that they
+    run fine on your configuration.
 
 Code Coverage
 -------------
@@ -83,7 +83,8 @@ Check the code coverage by opening the generated `cov/index.html` page in a
 browser.
 
 .. tip::
-   The code coverage only works if you have XDebug enabled and all dependencies
-   installed.
+
+    The code coverage only works if you have XDebug enabled and all
+    dependencies installed.
 
 .. _install: http://www.phpunit.de/manual/current/en/installation.html

contributing/community/index.rst

@@ -0,0 +1,8 @@
+Contributing Code
+=================
+
+.. toctree::
+    :maxdepth: 2
+
+    irc
+    other

contributing/community/irc.rst

@@ -0,0 +1,60 @@
+IRC Meetings
+============
+
+The purpose of this meeting is to discuss topics in real time with many of the
+Symfony2 devs.
+
+Anyone may propose topics on the `symfony-dev`_ mailing-list until 24 hours
+before the meeting, ideally including well prepared relevant information via
+some URL. 24 hours before the meeting a link to a `doodle`_ will be posted
+including a list of all proposed topics. Anyone can vote on the topics until
+the beginning of the meeting to define the order in the agenda. Each topic
+will be timeboxed to 15mins and the meeting lasts one hour, leaving enough
+time for at least 4 topics.
+
+.. caution::
+
+    Note that its not the expected goal of them meeting to find final
+    solutions, but more to ensure that there is a common understanding of the
+    issue at hand and move the discussion forward in ways which are hard to
+    achieve with less real time communication tools.
+
+Meetings will happen each Thursday at 17:00 CET (+01:00) on the #symfony-dev
+channel on the Freenode IRC server.
+
+The IRC `logs`_ will later be published on the trac wiki, which will include a
+short summary for each of the topics. Tickets will be created for any tasks or
+issues identified during the meeting and referenced in the summary.
+
+Some simple guidelines and pointers for participation:
+
+* It's possible to change votes until the beginning of the meeting by clicking
+  on "Edit an entry";
+* The doodle will be closed for voting at the beginning of the meeting;
+* Agenda is defined by which topics got the most votes in the doodle, or
+  whichever was proposed first in case of a tie;
+* At the beginning of the meeting one person will identify him/herself as the
+  moderator;
+* The moderator is essentially responsible for ensuring the 15min timebox and
+  ensuring that tasks are clearly identified;
+* Usually the moderator will also handle writing the summary and creating trac
+  tickets unless someone else steps up;
+* Anyone can join and is explicitly invited to participate;
+* Ideally one should familiarize oneself with the proposed topic before the
+  meeting;
+* When starting on a new topic the proposer is invited to start things off
+  with a few words;
+* Anyone can then comment as they see fit;
+* Depending on how many people participate one should potentially retrain
+  oneself from pushing a specific argument too hard;
+* Remember the IRC `logs`_ will be published later on, so people have the
+  chance to review comments later on once more;
+* People are encouraged to raise their hand to take on tasks defined during
+  the meeting.
+
+Here is an `example`_ doodle.
+
+.. _symfony-dev: http://groups.google.com/group/symfony-devs
+.. _doodle:      http://doodle.com
+.. _logs:        http://trac.symfony-project.org/wiki/Symfony2IRCMeetingLogs
+.. _example:     http://doodle.com/4cnzme7xys3ay53w

contributing/community/other.rst

@@ -0,0 +1,15 @@
+Other Resources
+===============
+
+In order to follow what is happening in the community you might find helpful
+these additional resources:
+
+ * List of open `pull requests`_
+ * List of recent `commits`_
+ * List of open `bugs`_
+ * List of open source `bundles`_
+
+.. _pull requests: https://github.com/fabpot/symfony/pulls
+.. _commits:       https://github.com/fabpot/symfony/commits/master
+.. _bugs:          http://trac.symfony-project.org/report/24
+.. _bundles:       http://symfony2bundles.org/

contributing/documentation/format.rst

@@ -8,7 +8,7 @@ reStructuredText
 ----------------
 
 reStructuredText "is an easy-to-read, what-you-see-is-what-you-get plaintext
-markup syntax and parser system."
+markup syntax and parser system".
 
 You can learn more about its syntax by reading existing Symfony2 `documents`_
 or by reading the `reStructuredText Primer`_ on the Sphinx website.
@@ -49,7 +49,8 @@ the highlighted pseudo-language:
         <?php echo $this->foobar(); ?>
 
 .. note::
-   A list of supported languages is available on the `Pygments website`_.
+
+    A list of supported languages is available on the `Pygments website`_.
 
 Configuration Blocks
 ~~~~~~~~~~~~~~~~~~~~
@@ -72,7 +73,7 @@ directive to show the configuration in all supported configuration formats
 
         .. code-block:: php
 
-            // Configuration in XML
+            // Configuration in PHP
 
 The previous reST snippet renders as follow:
 
@@ -88,7 +89,25 @@ The previous reST snippet renders as follow:
 
     .. code-block:: php
 
-        // Configuration in XML
+        // Configuration in PHP
+
+The current list of supported formats are the following:
+
+=============== ===========
+Markup format   Displayed
+=============== ===========
+html            HTML
+xml             XML
+php             PHP
+yaml            YAML
+jinja           Twig
+html+jinja      Twig
+jinja+html      Twig
+php+html        PHP
+html+php        PHP
+ini             INI
+php-annotations Annotations
+=============== ===========
 
 .. _reStructuredText:        http://docutils.sf.net/rst.html
 .. _Sphinx:                  http://sphinx.pocoo.org/

contributing/documentation/license.rst

@@ -29,7 +29,8 @@ Attribution-Share Alike 3.0 Unported `License`_.
   domain under applicable law, that status is in no way affected by the
   license;
 
-* *Other Rights* — In no way are any of the following rights affected by the license:
+* *Other Rights* — In no way are any of the following rights affected by the
+  license:
 
     * Your fair dealing or fair use rights, or other applicable copyright
       exceptions and limitations;

contributing/documentation/overview.rst

@@ -25,8 +25,9 @@ If you want to submit a patch, clone the official documentation repository:
     $ git clone git://github.com/symfony/symfony-docs.git
 
 .. note::
-  The Symfony2 documentation is licensed under a Creative Commons
-  Attribution-Share Alike 3.0 Unported :doc:`License <license>`.
+
+    The Symfony2 documentation is licensed under a Creative Commons
+    Attribution-Share Alike 3.0 Unported :doc:`License <license>`.
 
 Reporting an Issue
 ------------------