Added v3 -> v4 migration information

1 files changed, 111 insertions, 0 deletions

diff --git a/docs/migration.rst b/docs/migration.rst
index 72c07fd..ea7c904 100644
--- a/docs/migration.rst
+++ b/docs/migration.rst
@@ -2,6 +2,117 @@
 Migrating from previous versions of APScheduler
 ###############################################
 
+.. py:currentmodule:: apscheduler
+
+From v3.x to v4.0
+=================
+
+APScheduler 4.0 has undergone a partial rewrite since the 3.x series.
+
+There is currently no way to automatically import schedules from a persistent 3.x job
+store, but this shortcoming will be rectified before the final v4.0 release.
+
+Terminology and architectural design changes
+--------------------------------------------
+
+The concept of a *job* has been split into :class:`Task`, :class:`Schedule` and
+:class:`Job`. See the documentation of each class (and read the tutorial) to understand
+their roles.
+
+**Executors** have been replaced by *workers*. Workers were designed to be able to run
+independently from schedulers. Workers now *pull* jobs from the data store instead of
+the scheduler pushing jobs directly to them.
+
+**Data stores**, previously called *job stores*, have been redesigned to work with
+multiple running schedulers and workers, both for purposes of scalability and fault
+tolerance. Many data store implementations were dropped because they were either too
+burdensome to support, or the backing services were not sophisticated enough to handle
+the increased requirements.
+
+**Event brokers** are a new component in v4.0. They relay events between schedulers and
+workers, enabling them to work together with a shared data store. External (as opposed
+to local) event broker services are required in multi-node or multi-process deployment
+scenarios.
+
+**Triggers** are now stateful. This change was found to be necessary to properly support
+combining triggers (:class:`~.triggers.combining.AndTrigger` and
+:class:`~.triggers.combining.OrTrigger`), as they needed to keep track of the next run
+times of all the triggers contained within. This change also enables some more
+sophisticated custom trigger implementations.
+
+**Time zone** support has been revamped to use :mod:`zoneinfo` (or `backports.zoneinfo`_
+on Python versions earlier than 3.9) zones instead of pytz zones. You should not use
+pytz with APScheduler anymore.
+
+`Entry points`_ are no longer used or supported, as they were more trouble than they
+were worth, particularly with packagers like py2exe or PyInstaller which by default did
+not package distribution metadata. Thus, triggers and data stores have to be explicitly
+instantiated.
+
+.. _backports.zoneinfo: https://pypi.org/project/backports.zoneinfo/
+.. _Entry points: https://packaging.python.org/en/latest/specifications/entry-points/
+
+Scheduler changes
+-----------------
+
+The ``add_job()`` method is now :meth:`~Scheduler.add_schedule`. The scheduler still has
+a method named :meth:`~Scheduler.add_job`, but this is meant for making one-off runs of a
+task. Previously you would have had to call ``add_job()`` with a
+:class:`~apscheduler.triggers.date.DateTrigger` using the current time as the run time.
+
+The two most commonly used schedulers, ``BlockingScheduler`` and
+``BackgroundScheduler``, have often caused confusion among users and have thus been
+combined into :class:`~.schedulers.sync.Scheduler`. This new unified scheduler class
+has two methods that replace the ``start()`` method used previously:
+:meth:`~.schedulers.sync.Scheduler.run_until_stopped` and
+:meth:`~.schedulers.sync.Scheduler.start_in_background`. The former should be used if
+you previously used ``BlockingScheduler``, and the latter if you used
+``BackgroundScheduler``.
+
+The asyncio scheduler has been replaced with a more generic :class:`AsyncScheduler`,
+which is based on AnyIO_ and thus also supports Trio_ in addition to :mod:`asyncio`.
+The API of the async scheduler differs somewhat from its synchronous counterpart. In
+particular, it **requires** itself to be used as an async context manager – whereas with
+the synchronous scheduler, use as a context manager is recommended but not required.
+
+All other scheduler implementations have been dropped because they were either too
+burdensome to support, or did not seem necessary anymore. Some of the dropped
+implementations (particularly Qt) are likely to be re-added before v4.0 final.
+
+Schedulers no longer support multiple data stores. If you need this capability, you
+should run multiple schedulers instead.
+
+Configuring and running the scheduler has been radically simplified. The ``configure()``
+method is gone, and all configuration is now passed as keyword arguments to the
+scheduler class.
+
+.. _AnyIO: https://pypi.org/project/anyio/
+.. _Trio: https://pypi.org/project/trio/
+
+Trigger changes
+---------------
+
+As the scheduler is no longer used to create triggers, any supplied datetimes will be
+assumed to be in the local time zone. If you wish to change the local time zone, you
+should set the ``TZ`` environment variable to either the name of the desired timezone
+(e.g. ``Europe/Helsinki``) or to a path of a time zone file. See the tzlocal_
+documentation for more information.
+
+**Jitter** support has been moved from individual triggers to the schedule level.
+This not only simplified trigger design, but also enabled the scheduler to provide
+information about the randomized jitter and the original run time to the user.
+
+:class:`~.triggers.cron.CronTrigger` was changed to respect the standard order of
+weekdays, so that Sunday is now 0 and Saturday is 6. If you used numbered weekdays
+before, you must change your trigger configuration to match. If in doubt, use
+abbreviated weekday names (e.g. ``sun``, ``fri``) instead.
+
+:class:`~.triggers.interval.IntervalTrigger` was changed to start immediately, instead
+of waiting for the first interval to pass. If you have workarounds in place to "fix"
+the previous behavior, you should remove them.
+
+.. _tzlocal: https://pypi.org/project/tzlocal/
+
 From v3.0 to v3.2
 =================