[TASK] Prepare the 2.1.0 release (#640)

Closes #639

CHANGELOG.md

@@ -3,9 +3,20 @@
 All notable changes to this project will be documented in this file.
 This project adheres to [Semantic Versioning](https://semver.org/).
 
-
 ## x.y.z
 
+### Added
+
+### Changed
+
+### Deprecated
+
+### Removed
+
+### Fixed
+
+## 2.1.0
+
 ### Added
 - PHP 7.3 support
  ([#638](https://github.com/MyIntervals/emogrifier/pull/638))
@@ -37,6 +48,8 @@ This project adheres to [Semantic Versioning](https://semver.org/).
  ([#476](https://github.com/jjriv/emogrifier/pull/476))
 
 ### Changed
+- Mark the work-in-progress classes as `@internal`
+ ([#640](https://github.com/MyIntervals/emogrifier/pull/640))
 - Remove the unprocessable tags from the DOM, not from the raw HTML
  ([#627](https://github.com/MyIntervals/emogrifier/pull/627))
 - Reject empty HTML in `setHtml()`
@@ -107,7 +120,6 @@ This project adheres to [Semantic Versioning](https://semver.org/).
 - Allow CSS property values containing newlines
  ([#504](https://github.com/MyIntervals/emogrifier/pull/504))
 
-
 ## 2.0.0
 
 ### Added
@@ -159,7 +171,6 @@ This project adheres to [Semantic Versioning](https://semver.org/).
 - Silence purposefully ignored PHP Warnings
  ([#400](https://github.com/MyIntervals/emogrifier/pull/400))
 
-
 ## 1.2.0 (2017-03-02)
 
 ### Added
@@ -176,7 +187,6 @@ This project adheres to [Semantic Versioning](https://semver.org/).
 - Ignore "auto" width and height
  ([#365](https://github.com/MyIntervals/emogrifier/pull/365))
 
-
 ## 1.1.0 (2016-09-18)
 
 ### Added
@@ -221,7 +231,6 @@ This project adheres to [Semantic Versioning](https://semver.org/).
 - Second !important rule needs to overwrite the first one
  ([#292](https://github.com/MyIntervals/emogrifier/pull/292))
 
-
 ## 1.0.0 (2015-10-15)
 
 ### Added

README.md

@@ -37,14 +37,12 @@ into inline style attributes in your HTML code.
 - [Processing HTML](#processing-html)
 - [Maintainers](#maintainers)
 
-
 ## How it Works
 
 Emogrifier automagically transmogrifies your HTML by parsing your CSS and
 inserting your CSS definitions into tags within your HTML based on your CSS
 selectors.
 
-
 ## Installation
 
 For installing emogrifier, either add pelago/emogrifier to your
@@ -54,7 +52,6 @@ project's composer.json, or you can use composer as below:
 composer require pelago/emogrifier
 ```
 
-
 ## Usage
 
 First, you provide Emogrifier with the HTML and CSS you would like to merge.
@@ -78,7 +75,6 @@ $emogrifier->setHtml($html);
 $emogrifier->setCss($css);
 ```
 
-
 After you have set the HTML and CSS, you can call the `emogrify` method to
 merge both:
 
@@ -96,7 +92,6 @@ the complete HTML document, you can use the `emogrifyBodyContent` instead:
 $bodyContent = $emogrifier->emogrifyBodyContent();
 ```
 
-
 ## Options
 
 There are several options that you can set on the Emogrifier object before
@@ -133,7 +128,6 @@ calling the `emogrify` method:
  attributes set. This option will be removed in Emogrifier 3.0. Please use the
  `CssToAttributeConverter` class instead.
 
-
 ## Installing with Composer
 
 Download the [`composer.phar`](https://getcomposer.org/composer.phar) locally
@@ -146,27 +140,26 @@ curl -s https://getcomposer.org/installer | php
 Run the following command for a local installation:
 
 ```bash
-php composer.phar require pelago/emogrifier:^2.0.0
+php composer.phar require pelago/emogrifier:^2.1.0
 ```
 
 Or for a global installation, run the following command:
 
 ```bash
-composer require pelago/emogrifier:^2.0.0
+composer require pelago/emogrifier:^2.1.0
 ```
 
 You can also add follow lines to your `composer.json` and run the
 `composer update` command:
 
 ```json
 "require": {
- "pelago/emogrifier": "^2.0.0"
+ "pelago/emogrifier": "^2.1.0"
 }
 ```
 
 See https://getcomposer.org/ for more information and documentation.
 
-
 ## Supported CSS selectors
 
 Emogrifier currently supports the following
@@ -201,7 +194,6 @@ The following selectors are not implemented yet:
  (some of them will never be supported)
  * [pseudo-elements](https://developer.mozilla.org/en-US/docs/Web/CSS/Pseudo-elements)
 
-
 ## Caveats
 
 * Emogrifier requires the HTML and the CSS to be UTF-8. Encodings like
@@ -236,7 +228,6 @@ The following selectors are not implemented yet:
  works by converting CSS selectors to XPath selectors, and pseudo selectors
  cannot be converted accurately).
 
-
 ## Processing HTML
 
 The Emogrifier package also provides classes for (post-)processing the HTML
@@ -272,24 +263,28 @@ $converter = new \Pelago\Emogrifier\HtmlProcessor\CssToAttributeConverter($rawHt
 $visualHtml = $converter->convertCssToVisualAttributes()->render();
 ```
 
+### Technology preview of new classes
+
+Currently, a refactoring effort is underway, aiming towards replacing the
+grown-over-time `Emogrifier` class with the new `CssInliner` class and moving
+additional HTML processing into separate `CssProcessor` classes (which will
+inherit from `AbstractHtmlProcessor`). You can try the new classes, but be
+aware that the APIs of the new classes still are subject to change. 
 
 ## Steps to release a new version
 
 1. Create a pull request "Prepare release of version x.y.z" with the following
  changes.
-2. Set the new version number in the `@version` annotation in the class PHPDoc
- of [Emogrifier.php](src/Emogrifier.php).
-3. In the [composer.json](composer.json), update the `branch-alias` entry to
+1. In the [composer.json](composer.json), update the `branch-alias` entry to
  point to the release _after_ the upcoming release.
-4. In the [README.md](README.md), update the version numbers in the section
+1. In the [README.md](README.md), update the version numbers in the section
  [Installing with Composer](#installing-with-composer).
-5. In the [CHANGELOG.md](CHANGELOG.md), set the version number and remove any
+1. In the [CHANGELOG.md](CHANGELOG.md), set the version number and remove any
  empty sections.
-6. Have the pull request reviewed and merged.
-7. In the [Releases tab](https://github.com/MyIntervals/emogrifier/releases),
+1. Have the pull request reviewed and merged.
+1. In the [Releases tab](https://github.com/MyIntervals/emogrifier/releases),
  create a new release and copy the change log entries to the new release.
-8. Post about the new release on social media.
-
+1. Post about the new release on social media.
 
 ## Maintainers
 

src/Emogrifier/CssInliner.php

@@ -12,6 +12,8 @@
  *
  * For more information, please see the README.md file.
  *
+ * @internal This class currently is a new technology preview, and its API is still in flux. Don't use it in production.
+ *
  * @author Cameron Brooks
  * @author Jaime Prado
  * @author Oliver Klee <github@oliverklee.de>

src/Emogrifier/HtmlProcessor/AbstractHtmlProcessor.php

@@ -7,6 +7,8 @@
  *
  * The "vanilla" subclass is the HtmlNormalizer.
  *
+ * @internal This class currently is a new technology preview, and its API is still in flux. Don't use it in production.
+ *
  * @author Oliver Klee <github@oliverklee.de>
  */
 abstract class AbstractHtmlProcessor

src/Emogrifier/HtmlProcessor/CssToAttributeConverter.php

@@ -10,6 +10,8 @@
  *
  * To trigger the conversion, call the convertCssToVisualAttributes method.
  *
+ * @internal This class currently is a new technology preview, and its API is still in flux. Don't use it in production.
+ *
  * @author Oliver Klee <github@oliverklee.de>
  */
 class CssToAttributeConverter extends AbstractHtmlProcessor

src/Emogrifier/HtmlProcessor/HtmlNormalizer.php

@@ -9,6 +9,8 @@
  * - add HEAD and BODY elements (if they are missing)
  * - reformat the HTML
  *
+ * @internal This class currently is a new technology preview, and its API is still in flux. Don't use it in production.
+ *
  * @author Oliver Klee <github@oliverklee.de>
  */
 class HtmlNormalizer extends AbstractHtmlProcessor