From 3006120b28a70074a16586292213658a68249495 Mon Sep 17 00:00:00 2001 From: Ryan Weaver Date: Tue, 25 Mar 2014 22:38:20 -0400 Subject: [PATCH 1/8] [#3539] A backport of a sentence - the parts that apply to 2.3 --- components/stopwatch.rst | 5 +++++ 1 file changed, 5 insertions(+) diff --git a/components/stopwatch.rst b/components/stopwatch.rst index a839b432ddf..d7efdd62d07 100644 --- a/components/stopwatch.rst +++ b/components/stopwatch.rst @@ -35,6 +35,11 @@ microtime by yourself. Instead, use the simple // ... some code goes here $event = $stopwatch->stop('eventName'); +The :class:`Symfony\\Component\\Stopwatch\StopwatchEvent` object can be retrieved +from the :method:`Symfony\\Component\\Stopwatch\\Stopwatch::start`, +:method:`Symfony\\Component\\Stopwatch\\Stopwatch::stop` and +:method:`Symfony\\Component\\Stopwatch\\Stopwatch::lap` methods. + You can also provide a category name to an event:: $stopwatch->start('eventName', 'categoryName'); From 934b0215544b8a73126e7ae2afd4e0fb4998c652 Mon Sep 17 00:00:00 2001 From: Marie Minasyan Date: Thu, 19 Dec 2013 15:55:14 +0100 Subject: [PATCH 2/8] The host parameter has to be in defaults, not requirements --- components/routing/hostname_pattern.rst | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/components/routing/hostname_pattern.rst b/components/routing/hostname_pattern.rst index ae00531a96b..6085a358a78 100644 --- a/components/routing/hostname_pattern.rst +++ b/components/routing/hostname_pattern.rst @@ -194,8 +194,8 @@ instance, if you want to match both ``m.example.com`` and mobile_homepage: path: / host: "m.{domain}" - defaults: { _controller: AcmeDemoBundle:Main:mobileHomepage } - requirements: + defaults: + _controller: AcmeDemoBundle:Main:mobileHomepage domain: "%domain%" homepage: @@ -212,7 +212,7 @@ instance, if you want to match both ``m.example.com`` and AcmeDemoBundle:Main:mobileHomepage - %domain% + %domain% @@ -228,8 +228,8 @@ instance, if you want to match both ``m.example.com`` and $collection = new RouteCollection(); $collection->add('mobile_homepage', new Route('/', array( '_controller' => 'AcmeDemoBundle:Main:mobileHomepage', - ), array( 'domain' => '%domain%', + ), array( ), array(), 'm.{domain}')); $collection->add('homepage', new Route('/', array( From d552e69a3b7a7a913b76a79a2ea748abaf17fb5f Mon Sep 17 00:00:00 2001 From: Marie Minasyan Date: Wed, 26 Mar 2014 18:42:34 +0100 Subject: [PATCH 3/8] Moved tip block to remove confusion --- components/routing/hostname_pattern.rst | 16 ++++++++++------ 1 file changed, 10 insertions(+), 6 deletions(-) diff --git a/components/routing/hostname_pattern.rst b/components/routing/hostname_pattern.rst index 6085a358a78..e53229b6df2 100644 --- a/components/routing/hostname_pattern.rst +++ b/components/routing/hostname_pattern.rst @@ -176,17 +176,17 @@ instance, if you want to match both ``m.example.com`` and return $collection; -.. tip:: - - Make sure you also include a default option for the ``subdomain`` - placeholder, otherwise you need to include the subdomains value each time - you generate the route. - .. sidebar:: Using Service Parameters You can also use service parameters if you do not want to hardcode the hostname: + .. tip:: + + Make sure you also include a default option for the ``subdomain`` + placeholder, otherwise you need to include the subdomains value each time + you generate the route. + .. configuration-block:: .. code-block:: yaml @@ -197,6 +197,8 @@ instance, if you want to match both ``m.example.com`` and defaults: _controller: AcmeDemoBundle:Main:mobileHomepage domain: "%domain%" + requirements: + domain: "%domain%" homepage: path: / @@ -213,6 +215,7 @@ instance, if you want to match both ``m.example.com`` and AcmeDemoBundle:Main:mobileHomepage %domain% + %domain% @@ -230,6 +233,7 @@ instance, if you want to match both ``m.example.com`` and '_controller' => 'AcmeDemoBundle:Main:mobileHomepage', 'domain' => '%domain%', ), array( + 'domain' => '%domain%', ), array(), 'm.{domain}')); $collection->add('homepage', new Route('/', array( From 2030b282a0c04f44ede076238b71267370b12d21 Mon Sep 17 00:00:00 2001 From: Juan Manuel Date: Wed, 29 Jan 2014 21:59:16 -0200 Subject: [PATCH 4/8] Update file_uploads.rst Code examples do not apply to Doctrine EventSubscribers scenario, on preUpdate. Cheers. --- cookbook/doctrine/file_uploads.rst | 6 ++++++ 1 file changed, 6 insertions(+) diff --git a/cookbook/doctrine/file_uploads.rst b/cookbook/doctrine/file_uploads.rst index adb30e27e1f..f8a2113c3c5 100644 --- a/cookbook/doctrine/file_uploads.rst +++ b/cookbook/doctrine/file_uploads.rst @@ -371,6 +371,12 @@ Next, refactor the ``Document`` class to take advantage of these callbacks:: // do whatever you want to generate a unique name $filename = sha1(uniqid(mt_rand(), true)); $this->path = $filename.'.'.$this->getFile()->guessExtension(); + // Note: is you choose to use EvensubScribers, this change has no effect un database Update + // the 'initial' value set in {@link self::setFile()} is used instead. As this occurs + // inside EntityManager#flush() and changeSets are not tracked. + // use \Doctrine\Common\Persistence\Event\PreUpdateEventArgs $args as the handler fn param and + // $args->setNewValue('path', $filename); + // source: http://docs.doctrine-project.org/projects/doctrine-orm/en/latest/reference/events.html#preupdate } } From cc361fe98e0790c85a5c39cbf3f3d30a4d99af3b Mon Sep 17 00:00:00 2001 From: Juan Manuel Date: Tue, 4 Feb 2014 18:12:15 -0200 Subject: [PATCH 5/8] Update file_uploads.rst Updated as per @RyanWeaver's suggestions. --- cookbook/doctrine/file_uploads.rst | 16 ++++++++++------ 1 file changed, 10 insertions(+), 6 deletions(-) diff --git a/cookbook/doctrine/file_uploads.rst b/cookbook/doctrine/file_uploads.rst index f8a2113c3c5..683cfec10e6 100644 --- a/cookbook/doctrine/file_uploads.rst +++ b/cookbook/doctrine/file_uploads.rst @@ -371,12 +371,6 @@ Next, refactor the ``Document`` class to take advantage of these callbacks:: // do whatever you want to generate a unique name $filename = sha1(uniqid(mt_rand(), true)); $this->path = $filename.'.'.$this->getFile()->guessExtension(); - // Note: is you choose to use EvensubScribers, this change has no effect un database Update - // the 'initial' value set in {@link self::setFile()} is used instead. As this occurs - // inside EntityManager#flush() and changeSets are not tracked. - // use \Doctrine\Common\Persistence\Event\PreUpdateEventArgs $args as the handler fn param and - // $args->setNewValue('path', $filename); - // source: http://docs.doctrine-project.org/projects/doctrine-orm/en/latest/reference/events.html#preupdate } } @@ -416,6 +410,16 @@ Next, refactor the ``Document`` class to take advantage of these callbacks:: } } +.. caution:: + + When using Doctrine EvensubScribers' preUpdate(\Doctrine\Common\Persistence\Event\PreUpdateEventArgs $args) + callback instead of lifecycle callbacks you also need to invoke, ``$args->setNewValue('path', $filename);`` + as at this point changeSets are not updated and the ``path`` change just made won't have effect + in the data base record. + For full reference on preUpdate event restrictions, see `preUpdate`_ in the in the Doctrine Events documentation. + +.. _`preUpdate`: http://docs.doctrine-project.org/projects/doctrine-orm/en/latest/reference/events.html#preupdate + The class now does everything you need: it generates a unique filename before persisting, moves the file after persisting, and removes the file if the entity is ever deleted. From 8d00f1a232a34cb865cf16897759e160ed987038 Mon Sep 17 00:00:00 2001 From: Juan Manuel Date: Fri, 21 Mar 2014 17:35:25 -0300 Subject: [PATCH 6/8] Rewording Caution paragraph at line 413 --- cookbook/doctrine/file_uploads.rst | 23 ++++++++++++++++------- 1 file changed, 16 insertions(+), 7 deletions(-) diff --git a/cookbook/doctrine/file_uploads.rst b/cookbook/doctrine/file_uploads.rst index 683cfec10e6..9a1788fca97 100644 --- a/cookbook/doctrine/file_uploads.rst +++ b/cookbook/doctrine/file_uploads.rst @@ -410,15 +410,22 @@ Next, refactor the ``Document`` class to take advantage of these callbacks:: } } -.. caution:: +When using a Doctrine event listener or subscriber, when you make changes +to your entity, the preUpdate() callback must have an extra line of code to +tell Doctrine about the change:: - When using Doctrine EvensubScribers' preUpdate(\Doctrine\Common\Persistence\Event\PreUpdateEventArgs $args) - callback instead of lifecycle callbacks you also need to invoke, ``$args->setNewValue('path', $filename);`` - as at this point changeSets are not updated and the ``path`` change just made won't have effect - in the data base record. - For full reference on preUpdate event restrictions, see `preUpdate`_ in the in the Doctrine Events documentation. + public function preUpdate(PreUpdateEventArgs $args) + { + $entity = $args->getEntity(); + // do all the file uploading logic + // ... + $entity->setFilename($newFilename); + $args->setNewValue('filename', $newFilename); + } + +For full reference on preUpdate event restrictions, see `preUpdate`_ in the +Doctrine Events documentation. -.. _`preUpdate`: http://docs.doctrine-project.org/projects/doctrine-orm/en/latest/reference/events.html#preupdate The class now does everything you need: it generates a unique filename before persisting, moves the file after persisting, and removes the file if the @@ -556,3 +563,5 @@ You'll notice in this case that you need to do a little bit more work in order to remove the file. Before it's removed, you must store the file path (since it depends on the id). Then, once the object has been fully removed from the database, you can safely delete the file (in ``PostRemove``). + +.. _`preUpdate`: http://docs.doctrine-project.org/projects/doctrine-orm/en/latest/reference/events.html#preupdate From d920148e15254eaeabf5c89d0fb321558b203619 Mon Sep 17 00:00:00 2001 From: Juan Manuel Date: Mon, 24 Mar 2014 18:57:40 -0300 Subject: [PATCH 7/8] Going back to the ``Caution`` alternative. --- cookbook/doctrine/file_uploads.rst | 21 ++++++--------------- 1 file changed, 6 insertions(+), 15 deletions(-) diff --git a/cookbook/doctrine/file_uploads.rst b/cookbook/doctrine/file_uploads.rst index 9a1788fca97..f2bfd1601c1 100644 --- a/cookbook/doctrine/file_uploads.rst +++ b/cookbook/doctrine/file_uploads.rst @@ -410,22 +410,13 @@ Next, refactor the ``Document`` class to take advantage of these callbacks:: } } -When using a Doctrine event listener or subscriber, when you make changes -to your entity, the preUpdate() callback must have an extra line of code to -tell Doctrine about the change:: - - public function preUpdate(PreUpdateEventArgs $args) - { - $entity = $args->getEntity(); - // do all the file uploading logic - // ... - $entity->setFilename($newFilename); - $args->setNewValue('filename', $newFilename); - } - -For full reference on preUpdate event restrictions, see `preUpdate`_ in the -Doctrine Events documentation. +.. caution:: + If changes to your entity are handled by a Doctrine event listener or event + subscriber, the ``preUpdate()`` callback must notify Doctrine about the changes + being done. + For full reference on preUpdate event restrictions, see `preUpdate`_ in the + Doctrine Events documentation. The class now does everything you need: it generates a unique filename before persisting, moves the file after persisting, and removes the file if the From 17ee9bb24acd4b2225fc7873641b91726063710e Mon Sep 17 00:00:00 2001 From: Fabien Potencier Date: Thu, 6 Mar 2014 16:42:16 +0100 Subject: [PATCH 8/8] made some small addition about our BC promise and semantic versioning --- contributing/community/releases.rst | 59 +++++++++++++++++++---------- 1 file changed, 38 insertions(+), 21 deletions(-) diff --git a/contributing/community/releases.rst b/contributing/community/releases.rst index 1e8471d00d8..76ed0e1cc53 100644 --- a/contributing/community/releases.rst +++ b/contributing/community/releases.rst @@ -4,8 +4,15 @@ The Release Process This document explains the Symfony release process (Symfony being the code hosted on the main ``symfony/symfony`` `Git repository`_). -Symfony manages its releases through a *time-based model*; a new Symfony -release comes out every *six months*: one in *May* and one in *November*. +Symfony manages its releases through a *time-based model*; a new Symfony minor +version comes out every *six months*: one in *May* and one in *November*. + +.. tip:: + + The meaning of "minor" comes from the `Semantic Versioning`_ strategy. + +Each minor version sticks to the same very well-defined process where we start +with a development period, followed by a maintenance period. .. note:: @@ -18,7 +25,7 @@ release comes out every *six months*: one in *May* and one in *November*. Development ----------- -The six-months period is divided into two phases: +The first six-month period is divided into two phases: * *Development*: *Four months* to add new features and to enhance existing ones; @@ -36,8 +43,8 @@ final release. Maintenance ----------- -Each Symfony version is maintained for a fixed period of time, depending on -the type of the release. We have two maintenance periods: +Each Symfony minor version is maintained for a fixed period of time, depending +on the type of the release. We have two maintenance periods: * *Bug fixes and security fixes*: During this period, all issues can be fixed. The end of this period is referenced as being the *end of maintenance* of a @@ -47,17 +54,17 @@ the type of the release. We have two maintenance periods: be fixed. The end of this period is referenced as being the *end of life* of a release. -Standard Releases +Standard Versions ~~~~~~~~~~~~~~~~~ -A standard release is maintained for an *eight month* period for bug fixes, -and for a *fourteen month* period for security issue fixes. +A standard minor version is maintained for an *eight month* period for bug +fixes, and for a *fourteen month* period for security issue fixes. -Long Term Support Releases +Long Term Support Versions ~~~~~~~~~~~~~~~~~~~~~~~~~~ -Every two years, a new Long Term Support Release (aka LTS release) is -published. Each LTS release is supported for a *three year* period for bug +Every two years, a new Long Term Support Version (aka LTS version) is +published. Each LTS version is supported for a *three year* period for bug fixes, and for a *four year* period for security issue fixes. .. note:: @@ -109,17 +116,26 @@ This results in very predictable dates and maintenance periods: use the online `timeline calculator`_. You can also get all data as a JSON string via a URL like `http://symfony.com/roadmap.json?version=2.x`. +.. tip:: + + Whenever an important event related to Symfony versions happens (a version + reaches end of maintenance or a new patch version is released for + instance), you can automatically receive an email notification if you + subscribed on the `roadmap notification`_ page. + Backward Compatibility ---------------------- -After the release of Symfony 2.3, backward compatibility will be kept at all -cost. If it is not possible, the feature, the enhancement, or the bug fix will -be scheduled for the next major version: Symfony 3.0. +Our `Backwards Compatibility Promise`_ is very strict and allows developers to +upgrade with confidence from one minor version of Symfony to the next one. + +Whenever keeping backward compatibility is not possible, the feature, the +enhancement, or the bug fix will be scheduled for the next major version. .. note:: - The work on Symfony 3.0 will start whenever enough major features breaking - backward compatibility are waiting on the todo-list. + The work on a new major version of Symfony starts whenever enough major + features breaking backward compatibility are waiting on the todo-list. Deprecations ------------ @@ -154,11 +170,12 @@ for the next cycle. The dual maintenance mode was adopted to make every Symfony user happy. Fast movers, who want to work with the latest and the greatest, use the standard -releases: a new version is published every six months, and there is a two -months period to upgrade. Companies wanting more stability use the LTS -releases: a new version is published every two years and there is a year to -upgrade. +version: a new version is published every six months, and there is a two months +period to upgrade. Companies wanting more stability use the LTS versions: a new +version is published every two years and there is a year to upgrade. +.. _Semantic Versioning: http://semver.org/ .. _Git repository: https://github.com/symfony/symfony .. _SensioLabs: http://sensiolabs.com/ -.. _`timeline calculator`: http://symfony.com/roadmap +.. _roadmap notification: http://symfony.com/roadmap +.. _timeline calculator: http://symfony.com/roadmap