From ecb1fd81d32422ac475bfa8b7c0dce1d8063d3ba Mon Sep 17 00:00:00 2001
From: Chi <Chi@556138.no-reply.drupal.org>
Date: Tue, 15 Dec 2020 07:56:09 +0000
Subject: [PATCH] Issue #3174273: Add migration guide

---
 docs/migration-to-3.x.md | 50 ++++++++++++++++++++++++++++++++++++++++
 1 file changed, 50 insertions(+)
 create mode 100644 docs/migration-to-3.x.md

diff --git a/docs/migration-to-3.x.md b/docs/migration-to-3.x.md
new file mode 100644
index 0000000..185236f
--- /dev/null
+++ b/docs/migration-to-3.x.md
@@ -0,0 +1,50 @@
+# Migrating to Twig Tweak 3.x
+
+## Dependencies
+Twig Tweak 3.x requires Drupal 9, Twig 2 and PHP 7.3.
+
+## Rendering entities
+Entity ID parameter in `drupal_entity()` and `drupal_field()` functions is now mandatory. Previously it was possible to load entities from current route by omitting entity ID parameter. However, that was making Twig templates coupled with routes and could cause caching issues.
+
+Before:
+```twig
+{{ drupal_entity('node', null, 'teaser') }}
+```
+
+After:
+```twig
+{{ drupal_entity('node', node.id, 'teaser') }}
+```
+
+In case a template does not contain a variable with entity object you may prepare in a preprocess hook.
+
+```php
+/**
+ * Implements hook_preprocess_page().
+ */
+function preprocess_page(array &$variables): void {
+  $variables['entity'] = \Drupal::routeMatch()->getParameter('entity_type');
+}
+```
+
+## Rendering blocks
+`drupal_block()` now moves attributes provided by block plugin to the outer element. This may break some CSS rules.
+
+Before:
+```HTML
+<div>
+  <div class="from-block-plugin">Block content</div>
+</div>
+```
+
+After:
+```HTML
+<div class="from-block-plugin">
+  <div>Block content</div>
+</div>
+```
+
+See https://www.drupal.org/node/3068078 for details.
+
+## Documentation
+Cheat Sheet page has been moved to docs/cheat-sheet.md file shipped with the module. This allows to keep documentation in sync with project releases.