Adding a section about keeping BC in a re-usable bundle

cookbook/bundles/best_practices.rst

@@ -328,6 +328,43 @@ semantic configuration described in the cookbook.
     If you are defining services, they should also be prefixed with the bundle
     alias.
 
+Custom Validation Constraints
+-----------------------------
+
+Starting with Symfony 2.5, a new Validation API was introduced. In fact,
+there are 3 modes, which the user can configure in their project:
+
+* 2.4: the original 2.4 and earlier validation API;
+* 2.5: the new 2.5 and later validation API;
+* 2.5-BC: the new 2.5 API with a backwards-compatible layer so that the
+  2.4 API still works. This is only available in PHP 5.3.9+.
+
+As a bundle author, you'll want to support *both* API's, since some users
+may still be using the 2.4 API. Specifically, if your bundle adds a violation
+directly to the :class:`Symfony\Component\Validator\Context\ExecutionContext`
+(e.g. like in a custom validation constraint), you'll need to check for which
+API is being used. The following code, would work for *all* users::
+
+    class ContainsAlphanumericValidator extends ConstraintValidator
+    {
+        public function validate($value, Constraint $constraint)
+        {
+            if ($this->context instanceof ExecutionContextInterface) {
+                // the 2.5 API
+                $this->context->buildViolation($constraint->message)
+                    ->setParameter('%string%', $value)
+                    ->addViolation();
+                );
+            } else {
+                // the 2.4 API
+                $this->context->addViolation(
+                    $constraint->message,
+                    array('%string%' => $value)
+                );
+            }
+        }
+    }
+
 Learn more from the Cookbook
 ----------------------------