From 4c1f0cd538ec5cc0533f288c87760c75f4d31c89 Mon Sep 17 00:00:00 2001
From: Joseph Hamman <joe@earthmover.io>
Date: Tue, 13 Aug 2024 16:06:09 -0700
Subject: [PATCH] doc(v3): add start of v3 migration page

---
 docs/index.rst        |  1 +
 docs/installation.rst | 92 ++++++++++++++++++++++++++++++++++++-------
 2 files changed, 79 insertions(+), 14 deletions(-)

diff --git a/docs/index.rst b/docs/index.rst
index 92f9a3df18..cb7b61fa40 100644
--- a/docs/index.rst
+++ b/docs/index.rst
@@ -9,6 +9,7 @@ Zarr-Python
     :hidden:
 
     getting_started
+    migration
     tutorial
     api/index
     spec
diff --git a/docs/installation.rst b/docs/installation.rst
index 3d4ac41072..0ae4f7c013 100644
--- a/docs/installation.rst
+++ b/docs/installation.rst
@@ -1,22 +1,86 @@
-Installation
-============
+Zarr-Python 3 Migration Guide
+=============================
 
-Zarr depends on NumPy. It is generally best to `install NumPy
-<https://numpy.org/doc/stable/user/install.html>`_ first using whatever method is most
-appropriate for your operating system and Python distribution. Other dependencies should be
-installed automatically if using one of the installation methods below.
+Zarr-Python 3 introduces a number of changes to the API, including a number
+of significant breaking changes and pending deprecations.
 
-Install Zarr from PyPI::
+This page provides a guide highlighting the most notable changes to help you
+migrate your code from Zarr-Python 2.x to Zarr-Python 3.x.
 
-    $ pip install zarr
+Compatibility target
+--------------------
 
-Alternatively, install Zarr via conda::
+Zarr-Python 3 represents a major refactor of the Zarr-Python codebase. Some of the goals motivating this refactor included:
 
-    $ conda install -c conda-forge zarr
+  - adding support for the V3 specification (alongside the V3 specification)
+  - cleaning up internal and user facing APIs
+  - improving performance (particularly in high latency storage environments like cloud object store)
 
-To install the latest development version of Zarr, you can use pip with the
-latest GitHub main::
+Though these goals necessitated some breaking changes to the API (hence the major version update), we have tried to maintain
+backwards compatibility in the most widely used parts of the API including the `Array` and `Group` classes and the top-level
+API (e.g. `zarr.open_array` and `zarr.open_group`).
 
-    $ pip install git+https://github.com/zarr-developers/zarr-python.git
+Getting ready for 3.0
+---------------------
 
-To work with Zarr source code in development, see `Contributing <contributing.html>`_.
\ No newline at end of file
+Ahead of the 3.0 release, we suggest projects that depend on Zarr-Python take the following actions:
+
+1. Pin the supported Zarr-Python version to ``zarr>=2,<3``. This is a best practice and will protect your users from any incompatibilities that may arise during the release of Zarr-Python 3.0.
+2. Limit your imports from the Zarr-Python package. Most of the primary API ``zarr.*`` will be compatible in 3.0. However, the following breaking API changes are planned:
+   
+   - ``numcodecs.*`` will no longer be available in ``zarr.*``. (Suggested action: transition to importing codecs from ``numcodecs`` directly.)
+   - The ``zarr.v3_api_available`` feature flag is being removed. (Suggested action: this experimental feature was deprecated in v2.18.)
+   - The following internal modules are being removed or significant changed:
+   
+    - ``zarr.attrs``
+    - ``zarr.codecs``
+    - ``zarr.context``
+    - ``zarr.core``
+    - ``zarr.hierarchy``
+    - ``zarr.indexing``
+    - ``zarr.meta``
+    - ``zarr.meta_v1``
+    - ``zarr.storage``
+    - ``zarr.sync``
+    - ``zarr.types``
+    - ``zarr.util``
+
+Continue using Zarr-Python 2
+----------------------------
+
+Zarr-Python 2.x is still available, though we recommend migrating to Zarr-Python 3 for its improvements and new features.
+
+If you need to use the latest Zarr-Python 2 release, you can install it with:
+
+    $ pip install "zarr==2.*"
+
+
+Migration Guide
+---------------
+
+The following sections provide details on the most important changes in Zarr-Python 3.
+
+Changes to the Array class
+~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+TODO
+
+Changes to the Group class
+~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+TODO
+
+Changes to the Store class
+~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Some of the biggest changes in Zarr-Python 3 are found in the `Store` class. The most notable changes to the Store API are:
+
+1. Dropped the ``MutableMapping`` base class in favor of a custom abstract base class (``zarr.abc.store.Store``).
+2. Switched to a primarily Async interface.
+
+TODO
+
+Miscellaneous changes
+~~~~~~~~~~~~~~~~~~~~~
+
+TODO