Update migration guide for 2.1 (#18729)

Author: awaelchli

docs/source-pytorch/upgrade/from_2_0.rst

@@ -0,0 +1,16 @@
+:orphan:
+
+Regular User
+************
+
+.. include:: sections/2_0_regular.rst
+
+Advanced User
+*************
+
+.. include:: sections/2_0_advanced.rst
+
+Developer
+*********
+
+.. include:: sections/2_0_devel.rst

docs/source-pytorch/upgrade/migration_guide.rst

@@ -1,20 +1,26 @@
-2.0 upgrade guide
+2.0 Upgrade Guide
 #################
 
-The following section will guide you through updating to the 2.0 release.
+The following section will guide you through updating your code to the 2.x series of releases.
 
 Particular versions
 *******************
 
 
-
 .. raw:: html
 
     <div class="display-card-container">
         <div class="row">
 
 .. Add callout items below this line
 
+.. displayitem::
+   :header: 2.0.x
+   :description: Upgrade from 2.0.x series to the 2.1.
+   :col_css: col-md-12
+   :button_link: from_2_0.html
+   :height: 100
+
 .. displayitem::
    :header: 1.9.x
    :description: Upgrade from 1.9.x series to the 2.0.

docs/source-pytorch/upgrade/sections/2_0_advanced.rst

@@ -0,0 +1,40 @@
+.. list-table:: adv. user 2.0
+   :widths: 40 40 20
+   :header-rows: 1
+
+   * - If
+     - Then
+     - Ref
+
+   * - used the ``torchdistx`` package and integration in Trainer
+     - materialize the model weights manually, or follow our :doc:`guide for initializing large models <../../advanced/model_init>`
+     - `PR17995`_
+
+   * - defined ``def training_step(self, dataloader_iter, batch_idx)`` in LightningModule
+     - remove ``batch_idx`` from the signature and expect ``dataloader_iter`` to return a triplet ``(batch, batch_idx, dataloader_idx)``
+     - `PR18390`_
+
+   * - defined ``def validation_step(self, dataloader_iter, batch_idx)`` in LightningModule
+     - remove ``batch_idx`` from the signature and expect ``dataloader_iter`` to return a triplet ``(batch, batch_idx, dataloader_idx)``
+     - `PR18390`_
+
+   * - defined ``def test_step(self, dataloader_iter, batch_idx)`` in LightningModule
+     - remove ``batch_idx`` from the signature and expect ``dataloader_iter`` to return a triplet ``(batch, batch_idx, dataloader_idx)``
+     - `PR18390`_
+
+   * - defined ``def predict_step(self, dataloader_iter, batch_idx)`` in LightningModule
+     - remove ``batch_idx`` from the signature and expect ``dataloader_iter`` to return a triplet ``(batch, batch_idx, dataloader_idx)``
+     - `PR18390`_
+
+   * - used ``batch = next(dataloader_iter)`` in LightningModule ``*_step`` hooks
+     - use ``batch, batch_idx, dataloader_idx = next(dataloader_iter)``
+     - `PR18390`_
+
+   * - relied on automatic detection of Kubeflow environment
+     - use ``Trainer(plugins=KubeflowEnvironment())`` to explicitly set it on a Kubeflow cluster
+     - `PR18137`_
+
+
+.. _pr17995: https://github.com/Lightning-AI/lightning/pull/17995
+.. _pr18390: https://github.com/Lightning-AI/lightning/pull/18390
+.. _pr18137: https://github.com/Lightning-AI/lightning/pull/18390

docs/source-pytorch/upgrade/sections/2_0_devel.rst

@@ -0,0 +1,18 @@
+.. list-table:: devel 2.0
+   :widths: 40 40 20
+   :header-rows: 1
+
+   * - If
+     - Then
+     - Ref
+
+   * - used the ``XLAStrategy.is_distributed`` property
+     - it was removed because it was always True
+     - `PR17381`_
+
+   * - used the ``SingleTPUStrategy.is_distributed`` property
+     - it was removed because it was always False
+     - `PR17381`_
+
+
+.. _pr17381: https://github.com/Lightning-AI/lightning/pull/17381

docs/source-pytorch/upgrade/sections/2_0_regular.rst

@@ -0,0 +1,57 @@
+.. list-table:: reg. user 2.0
+   :widths: 40 40 20
+   :header-rows: 1
+
+   * - If
+     - Then
+     - Ref
+
+   * - used PyTorch 3.11
+     - upgrade to PyTorch 2.1 or higher
+     - `PR18691`_
+
+   * - called ``self.trainer.model.parameters()`` in ``LightningModule.configure_optimizers()`` when using FSDP
+     - On PyTorch 2.0+, call ``self.parameters()`` from now on
+     - `PR17309`_
+
+   * - used ``Trainer(accelerator="tpu", devices=[i])"`` to select the 1-based TPU core index
+     - the index is now 0-based
+     - `PR17227`_
+
+   * - used ``torch_xla < 1.13``
+     - upgrade to ``torch_xla >= 1.13``
+     - `PR17368`_
+
+   * - used ``trainer.num_val_batches`` to get the total size of all validation dataloaders
+     - use ``sum(trainer.num_val_batches)``
+     - `PR18441`_
+
+   * - used ``trainer.num_test_batches`` to get the total size of all test dataloaders
+     - use ``sum(trainer.num_test_batches)``
+     - `PR18441`_
+
+   * - used ``trainer.num_sanity_val_batches`` to get the total size of all validation dataloaders for sanity checking
+     - use ``sum(trainer.num_sanity_val_batches)``
+     - `PR18441`_
+
+   * - used ``Trainer(devices="auto")`` to auto-select all available GPUs in a Jupyter notebook
+     - use ``Trainer(devices=-1)``
+     - `PR18291`_
+
+   * - used ``Trainer(devices="auto")`` to auto-select all available GPUs in a Jupyter notebook
+     - use ``Trainer(devices=-1)``
+     - `PR18291`_
+
+   * - ``pip install lightning`` to install ``lightning.app`` dependencies
+     - use ``pip install lightning[app]`` if you need ``lightning.app``
+     - `PR18386`_
+
+
+.. _pr18691: https://github.com/Lightning-AI/lightning/pull/18691
+.. _pr16579: https://github.com/Lightning-AI/lightning/pull/16579
+.. _pr17309: https://github.com/Lightning-AI/lightning/pull/17309
+.. _pr17227: https://github.com/Lightning-AI/lightning/pull/17227
+.. _pr17368: https://github.com/Lightning-AI/lightning/pull/17368
+.. _pr18441: https://github.com/Lightning-AI/lightning/pull/18441
+.. _pr18291: https://github.com/Lightning-AI/lightning/pull/18291
+.. _pr18386: https://github.com/Lightning-AI/lightning/pull/18386