Merge pull request #31196 from scottshambaugh/rcparam_docs

timhoffm · web-flow · commit cd25d229c805 · 2026-02-25T23:45:33.000+01:00
DOC: Document which files need to be updated for new rcparams
diff --git a/doc/devel/api_changes.rst b/doc/devel/api_changes.rst
@@ -32,6 +32,20 @@ take particular care when adding new API:
   __ https://emptysqua.re/blog/api-evolution-the-right-way/#adding-parameters
 
 
+Add new rcParams
+^^^^^^^^^^^^^^^^
+
+When adding a new rcParam, the following files must be updated:
+
+1. :file:`lib/matplotlib/rcsetup.py` - Add a validator entry to the
+   ``_validators`` dict and a corresponding ``_Param`` entry with default value
+   and description.
+2. :file:`lib/matplotlib/mpl-data/matplotlibrc` - Add a commented-out entry
+   showing the default value.
+3. :file:`lib/matplotlib/typing.py` - Add the key to the ``RcKeyType`` Literal
+   so that it is recognized as a valid rcParam key.
+
+
 Add or change colormaps, color sequences, and styles
 ----------------------------------------------------
 Visual changes are considered an API break. Therefore, we generally do not modify
diff --git a/doc/release/next_whats_new/README.rst b/doc/release/next_whats_new/README.rst
@@ -11,8 +11,8 @@ Instructions for writing "What's new" entries
 =============================================
 .. whats-new-guide-start
 
-Each new feature (e.g. function, parameter, config value, behavior, ...) must
-be described through a "What's new" entry.
+Each new feature (e.g. function, parameter, rcParam, config value, behavior,
+...) must be described through a "What's new" entry.
 
 Each entry is written into a separate file in the
 :file:`doc/release/next_whats_new/` directory. They are sorted and merged into
diff --git a/lib/matplotlib/rcsetup.py b/lib/matplotlib/rcsetup.py
@@ -10,7 +10,8 @@
 The default values of the rc settings are set in the default matplotlibrc file.
 Any additions or deletions to the parameter set listed here should also be
 propagated to the :file:`lib/matplotlib/mpl-data/matplotlibrc` in Matplotlib's
-root source directory.
+root source directory. New rcparams also need to be added to the RcKeyType enum
+in :file:`lib/matplotlib/typing.py`.
 """
 
 
