Merge pull request #2800 from timber/2794-timber-20-and-the-plugin-ve…

…rsion

Add documentation and plugin notice about the end of the plugin version

README.md

@@ -19,6 +19,11 @@ By
 [![WordPress Rating](https://img.shields.io/wordpress/plugin/r/timber-library.svg?style=flat-square)](https://wordpress.org/support/plugin/timber-library/reviews/)
 [![!Financial Contributors](https://opencollective.com/timber/tiers/badge.svg)](https://opencollective.com/timber/)
 
+### ⚠️ Important information about the Timber plugin ⚠️ 
+> With the release of Timber 2.0, Composer is the only supported install method. We are unable to continue releasing or supporting Timber as a plugin on WordPress.org. We advise everyone to **[switch to the Composer based install of Timber 1 as a first step](https://timber.github.io/docs/getting-started/switch-to-composer/)** as soon as possible. If you need PHP 8.2 support you will have to switch to Timber 2.0.
+
+For more information and a list of additional resources, please visit this [discussion](https://github.com/timber/timber/discussions/2804).
+
 ### Because WordPress is awesome, but the_loop isn't
 Timber helps you create fully-customized WordPress themes faster with more sustainable code. With Timber, you write your HTML using the [Twig Template Engine](https://twig.symfony.com/) separate from your PHP files.
 

docs/getting-started/setup.md

@@ -7,14 +7,22 @@ menu:
 ---
 
 ## Installation
+> ⚠️ **Important information about the Timber plugin**
+> With the release of Timber 2.0, Composer is the only supported install method. We are unable to continue releasing or supporting Timber as a plugin on WordPress.org. We advise everyone to **[switch to the Composer based install of Timber 1 as a first step](https://timber.github.io/docs/getting-started/switch-to-composer/)** as soon as possible. If you need PHP 8.2 support you will have to switch to Timber 2.0.
 
-### Via WordPress.org (easy)
+Underneath this text you will find an extensive list with guides and the reasons why we are not going to release Timber 2 in plugin version anymore.
 
-You can grab the all-things-included plugin at [WordPress.org](http://wordpress.org/plugins/timber-library/) either through the WordPress site or through the Plugins menu in the backend. Then skip ahead to [using the starter theme](#use-the-starter-theme).
+* Guide: [How do I switch over from the plugin version to the Composer based version of Timber?](https://timber.github.io/docs/getting-started/switch-to-composer/)
+* Backstory: [Why we are dropping support for the plugin in the first place](https://github.com/timber/timber/pull/2005)
+* Github issue: [Road to Timber 2.0](https://github.com/timber/timber/issues/2741)
 
-### Via GitHub (for developers)
+### ~~Via WordPress.org (easy)~~
 
-The GitHub version of Timber requires [Composer](https://getcomposer.org/download/). If you'd prefer one-click installation, you should use the [WordPress.org](https://wordpress.org/plugins/timber-library/) version.
+~~You can grab the all-things-included plugin at [WordPress.org](http://wordpress.org/plugins/timber-library/) either through the WordPress site or through the Plugins menu in the backend. Then skip ahead to [using the starter theme](#use-the-starter-theme).~~
+
+### Via Composer (recommended)
+
+The GitHub version of Timber requires [Composer](https://getcomposer.org/download/).
 
 Run the following Composer command from within your theme's root directory:
 

docs/getting-started/switch-to-composer.md

@@ -0,0 +1,74 @@
+---
+title: "Switch to Composer"
+description: "How to switch your plugin based Timber theme over to the Composer based version."
+menu:
+  main:
+    parent: "getting-started"
+---
+
+With the release of Timber 2.0, Composer is the only supported install method. We are unable to continue releasing or supporting Timber as a plugin on WordPress.org. We advise everyone to switch to the Composer based install of Timber 1 as soon as possible as a first step towards upgrading to Timber 2.
+
+## Recommended upgrade path
+
+1. Get a local development version of your website up and running.
+2. Check if you are running the latest version of the Timber plugin. If not, update it and check if your website still runs as expected.
+3. Disable the Timber plugin
+4. Install the latest 1.x version of Timber via Composer
+5. Load the Composer autoloader and initialize Timber
+6. Check if your website still runs as expected
+7. Deploy your changes to your live website
+
+
+### 1. Get a local development version of your website up and running
+We highly recommend doing these steps on a local development version of your website. If you don’t have one yet, you could use [Local by Flywheel](https://localbyflywheel.com/) to get one up and running in a few minutes.
+
+#### 1.1 How to install Composer
+If you don’t have Composer installed yet, you can follow the [official installation guide](https://getcomposer.org/doc/00-intro.md).
+
+
+### 2. Check if you are running the latest version of the Timber plugin
+We want to make sure that you are running the latest version of the Timber plugin before we start the upgrade process. This way we can be sure that any issues that might occur are not caused by an outdated version of the plugin.
+
+### 3. Disable the Timber plugin
+Once you are sure that you are running the latest version of the Timber plugin, you can disable it. This will make sure that the plugin is not loaded anymore and does not interfere with the Composer based version of Timber.
+
+Please note that you website will throw erros at this point, as there is no Timber available. This will be fixed in the next two steps.
+
+### 4. Install the latest 1.x version of Timber via Composer
+Now that the plugin is disabled, you can install the latest 1.x version of Timber via Composer. You can do this by navigating to your site's active theme folder inside your terminal and then running the following command:
+
+```shell
+composer require timber/timber:^1.0
+```
+
+If Composer gives you the following notice:
+
+```shell
+composer/installers contains a Composer plugin [...] (writes "allow-plugins" to composer.json)
+```
+it is safe to answer `y` to this question and press enter.
+
+
+### 5. Load the Composer autoloader and initialize Timber
+Now that we have Timber installed via Composer, we need to load the Composer autoloader and initialize Timber. You can do this by adding the following code at the top of your **functions.php** file:
+
+```php
+// Load Composer dependencies.
+require_once __DIR__ . '/vendor/autoload.php';
+
+$timber = new Timber\Timber();
+```
+
+### 6. Check if your website still runs as expected
+Now that you have Timber installed via Composer, you can check if your website still runs as expected. If you run into any issues, please try to solve them yourself by activating [WordPress debugging](https://wordpress.org/documentation/article/debugging-in-wordpress/) and checking the error logs.
+
+### 7. Deploy your changes to your live website
+When you are 100% sure that you have successfully upgraded your theme in the development website to the Composer based version of Timber, you can deploy your theme changes to your live website.
+
+Make sure that the new **vendor** folder inside your theme gets deployed as well. If you are using a deployment pipeline, you can commit your changes and push to your live website.
+
+If you are not using a version control system, you can use FTP or SCP to upload your changes to your theme.
+
+As a last step, you should disable and then remove the Timber v1 plugin from your live website.
+
+Congrats - you successfully moved to the Composer-based install and are prepared to later [upgrade to Timber v2](https://timber.github.io/docs/v2/upgrade-guides/2.0/).

lib/Admin.php

@@ -6,13 +6,25 @@ class Admin {
 
 	public static function init() {
 		$filter = add_filter('plugin_row_meta', array(__CLASS__, 'meta_links'), 10, 2);
+		$action = add_action('after_plugin_row_timber-library/timber.php', array(__CLASS__, 'show_deprecation_warning'), 10, 3);
 		$action = add_action('in_plugin_update_message-timber-library/timber.php', array(__CLASS__, 'in_plugin_update_message'), 10, 2);
 		$action = add_action('in_plugin_update_message-timber/timber.php', array(__CLASS__, 'in_plugin_update_message'), 10, 2);
 		if ( $filter && $action ) {
 			return true;
 		}
 	}
 
+	/**
+	 * show additional information about the plugin deprecation.
+	 *
+	 * @param string  $file
+	 * @param array   $plugin
+	 */
+	public static function show_deprecation_warning($file, $plugin, $status)
+	{
+		echo '<td colspan="3" class="plugin-update colspanchange"><div class="update-message notice-error notice inline notice-warning notice-alt"><p>We recommend <a target="_blank" href="https://timber.github.io/docs/getting-started/switch-to-composer/">switching to the Composer based version</a> of Timber. <a href="https://github.com/timber/timber/discussions/2804" target="_blank">Why you need to switch.</a></p></div></td>';
+	}
+
 	/**
 	 * @param array   $links
 	 * @param string  $file

readme.txt

@@ -11,6 +11,15 @@ License URI: http://www.gnu.org/licenses/gpl-2.0.html
 Helps you create themes faster with sustainable code. With Timber, you write HTML using Twig Templates http://www.upstatement.com/timber/
 
 == Description ==
+With the upcoming release of Timber 2.0, we will not release a 2.0 version and beyond as a plugin, but only as a Composer package. We advise everyone to switch to the Composer based install as soon as possible.
+You will find an extensive list with guides and the reasons why we are not going to release Timber 2.0 as a plugin anymore.
+
+### Switching to the Composer based version
+* Announcement: [Dropping support for the plugin version of Timber](https://github.com/timber/timber/discussions/2804)
+* Guide: [How do I switch over from the plugin version to the Composer based version of Timber?](https://timber.github.io/docs/getting-started/switch-to-composer/)
+* Backstory: [Why we are dropping support for the plugin in the first place](https://github.com/timber/timber/pull/2005)
+* GitHub issue: [Roadmap for Timber 2.0](https://github.com/timber/timber/issues/2741)
+
 Timber helps you create fully-customized WordPress themes faster with more sustainable code. With Timber, you write your HTML using the [Twig Template Engine](http://twig.sensiolabs.org/) separate from your PHP files. This cleans up your theme code so, for example, your PHP file can focus on being the data/logic, while your Twig file can focus 100% on the HTML and display.
 
 Once Timber is installed and activated in your plugin directory, it gives any WordPress theme the ability to take advantage of the power of Twig and other Timber features.