From 2b1718a2e73e8cd810c4ca5315f7d0be06037e55 Mon Sep 17 00:00:00 2001
From: Fabien Potencier <fabien@potencier.org>
Date: Mon, 18 Jan 2021 08:25:55 +0100
Subject: [PATCH] Clarify how to update recipes

---
 README.rst | 16 ++++++++++++++++
 1 file changed, 16 insertions(+)

diff --git a/README.rst b/README.rst
index fd6311eb..edca3d05 100644
--- a/README.rst
+++ b/README.rst
@@ -47,6 +47,22 @@ options and configurators.
     When creating a recipe, don't create bundle config files under
     ``config/packages/`` when no options are set.
 
+Updating Recipes
+----------------
+
+When a recipe needs to be updated, we try to minimize the impact for the
+current versions. Creating a new project with a set of dependencies should
+always use the same recipes to avoid differences between the generated code and
+the existing documentation, blog posts, videos for these versions.
+
+As a rule of thumb, consider the same principles as semantic versioning:
+
+* Only change an existing recipe for a version in case of a bug (typos,
+  mis-configuration, ...);
+
+* If the change is about a new best practice or a different way of doing
+  something, do it for the next version of the dependency.
+
 Options
 -------