DOC: add instructions for updating environment

doc/source/development/contributing.rst

@@ -331,6 +331,26 @@ To automatically fix formatting errors on each commit you make, you can
 set up pre-commit yourself. First, create a Python :ref:`environment
 <contributing_environment>` and then set up :ref:`pre-commit <contributing.pre-commit>`.
 
+.. _contributing.update-dev:
+
+Updating the development environment
+------------------------------------
+
+After updating your branch to merge in main from upstream, you may need to update
+your development environment to reflect any changes to the various packages that
+are used during development.
+
+If using :ref:`mamba <contributing.mamba>`, do::
+
+    mamba deactivate
+    mamba env update -f environment.yml
+    mamba activate pandas-dev
+
+If using :ref:`pip <contributing.pip>` , do::
+
+    # activate the virtual environment based on your platform
+    pythom -m pip install --upgrade -r requirements-dev.txt
+
 Tips for a successful pull request
 ==================================
 

doc/source/development/contributing_codebase.rst

@@ -89,6 +89,12 @@ without needing to have done ``pre-commit install`` beforehand.
     you may run into issues if you're using conda. To solve this, you can downgrade
     ``virtualenv`` to version ``20.0.33``.
 
+.. note::
+
+    If you have recently merged in main from the upstream branch, some of the
+    dependencies used by ``pre-commit`` may have changed.  Make sure to
+    :ref:`update your development environment <contributing.update-dev>`.
+
 Optional dependencies
 ---------------------
 

doc/source/development/contributing_environment.rst

@@ -95,6 +95,8 @@ Option 1: using mamba (recommended)
    mamba env create --file environment.yml
    mamba activate pandas-dev
 
+.. _contributing.pip:
+
 Option 2: using pip
 ~~~~~~~~~~~~~~~~~~~