First draft of 2.4 upgrade guide (#375)

* First draft of 2.4 upgrade guide

Add the most important changes coming in 2.4.0. I didn't do an
exhaustive method list as I didn't feel that was as useful as giving the
high level changes and rationale for those changes.

* Apply suggestions from code review

Co-authored-by: Edgaras Janušauskas <edgaras.janusauskas@gmail.com>

Co-authored-by: Edgaras Janušauskas <edgaras.janusauskas@gmail.com>

docs/en/2-4-upgrade-guide.rst

@@ -0,0 +1,78 @@
+2.4 Upgrade Guide
+#################
+
+Chronos 2.4 introduces a number of deprecations that will help you prepare your
+application for the upcoming Chronos 3.x release. This guide covers the
+deprecations introduced in 2.4 and gives a preview of what to expect in 3.0.
+
+No more mutable objects
+=======================
+
+Chronos was an early adopter of PHP's immutable datetime objects. With PHP
+moving away from mutable datetime objects both ``Cake\Chronos\MutableDate`` and
+``Cake\Chronos\MutaleDateTime`` are deprecated and will be removed in 3.0.0.
+
+To upgrade, replace usage of ``MutableDate`` with ``ChronosDate`` and
+``MutableDateTime`` with ``Chronos``. When modifying datetimes be sure to
+always re-assign the variable with the datetime::
+
+    // Mutate in place
+    $datetime->modify('+1 days');
+
+    // Immutable objects must re-assign
+    $datetime = $datetime->modify('+1 days');
+
+ChronosInterface deprecated
+===========================
+
+Having a consistent interface between date and datetime objects has proven to be
+problematic. It created an illusion of compatibility between mutable and
+immutable objects and date and datetime objects. Because the
+``ChronosInterface`` didn't and can't really deliver on the goals of interfaces
+it is deprecated, and will be removed in 3.0. To update your code replace
+references to ``ChronosInterface`` with either a reference to
+``Cake\Chronos\Chronos`` for datetime instances or ``Cake\Chronos\ChronosDate``
+for date instances.
+
+Fewer mutation methods
+======================
+
+For historical reasons the chronos classes included many redundant methods. For
+example ``addYear()`` and ``addYears()``. In 2.4.0, all of the singular methods
+e.g. ``addYear()`` are deprecated. Instead use the plural versions of the
+methods e.g. ``addYears()``.
+
+Simpler Date class
+==================
+
+When date abstractions were introduced they shared an interfaces with DateTime
+classes. This resulted in many no-op methods on dates. For example calling
+``setTime()`` on a date would have no effect. In 2.4, all time related methods
+(including timezones) are deprecated on date instances. If your application
+needs to use the time component of a date, you should use ``Chronos`` instead.
+
+Upcoming removals in 3.0
+========================
+
+The following changes will arrive in 3.0, and don't have a simple deprecation
+path. Unfortunately these changes will result in hard breaks in 3.0.
+
+Carbon aliases removed
+----------------------
+
+When Chronos was started Carbon had no active maintainers. We included
+compatiblity aliases in Chronos to help users migrate from the unmaintained
+Carbon library to Chronos. Presently, Carbon has active maintainers and we no
+longer feel the need to provide shims.
+
+No longer extending DateTime
+----------------------------
+
+Historically Chronos has extended PHP's ``DateTime`` classes. This has proven to
+be problematic especially for date classes. While Chronos will not extend
+PHP's ``DateTime`` classes or implements the ``DateTimeInterface``, if a method does
+not emit a deprecation in 2.4.0 it will continue to work in 3.0.
+
+To adapt to this change before upgrading to 3.0 replace references to PHP's
+``DateTime`` and ``DateTimeInterface`` and use ``Chronos`` or ``ChronosDate``
+instead.

docs/en/contents.rst

@@ -3,5 +3,6 @@
     :caption: CakePHP Chronos
 
     /index
+    /2-4-upgrade-guide
 
-    API <https://api.cakephp.org/chronos>
+    API <https://api.cakephp.org/chronos>