From 77b9535c3c3841a553abaa931738e1ea45569a3c Mon Sep 17 00:00:00 2001
From: Christian Roth <code@christianroth.dev>
Date: Wed, 1 May 2024 21:48:17 +0200
Subject: [PATCH 1/3] multi-output: document full/lite splits for optional
 dependencies.

---
 docs/maintainer/knowledge_base.md | 31 +++++++++++++++++++++++++++++++
 1 file changed, 31 insertions(+)

diff --git a/docs/maintainer/knowledge_base.md b/docs/maintainer/knowledge_base.md
index 3f3f403a52..a45a51ce66 100644
--- a/docs/maintainer/knowledge_base.md
+++ b/docs/maintainer/knowledge_base.md
@@ -1655,6 +1655,37 @@ add some information on r packages which make heavy use of `noarch: generic`
     - [importlib_metadata and importlib-metadata](https://github.com/conda-forge/importlib_metadata-feedstock/blob/main/recipe/meta.yaml)
     - [typing_extensions and typing-extensions](https://github.com/conda-forge/typing_extensions-feedstock/blob/main/recipe/meta.yaml)
 
+### Common patterns
+
+#### Splitting out heavy optional dependencies
+
+When a package has especially large optional dependencies it can be useful to split the package into a "lite" version that depends only on the core dependencies and a "full" version that depends on the "lite" version and all optional dependencies. The `pin_subpackage` function helps to ensure that the "full" version will pull the exact version of the "lite" version. As an example consider the [seaborn recipe](https://github.com/conda-forge/seaborn-feedstock/blob/eec88f0116a26c2e205daab10193e38e96407cab/recipe/meta.yaml) with optional statsmodels dependency:
+
+```yaml
+  - name: seaborn
+    build:
+      noarch: python
+    requirements:
+      run:
+        - statsmodels >=0.12
+        - {{ pin_subpackage('seaborn-base', exact=True) }}
+```
+
+In order to prevent the "lite" version `seaborn-base` to pull in seaborn versions before the package split, `run_constrained` will ensure that the `seaborn-base` package can only be installed together with the matching version of the `seaborn` package.
+
+```yaml
+  - name: seaborn-base
+    build:
+      noarch: python
+    requirements:
+      run_constrained:
+        - seaborn ={{ version }}=*_{{ build }}
+```
+
+:::important
+Counter-intuitively `{{ pin_subpackage('seaborn-base', exact=True) }}` will only work in the requirements section but not in `run_constrained` (see [conda-build#4415](https://github.com/conda/conda-build/issues/4415)). Use `seaborn ={{ version }}=*_{{ build }}` to ensure that the `seaborn-base` package can only be installed with the matching version of the `seaborn` package.
+:::
+
 ### Common pitfalls with `outputs`
 
 This is a non-exhaustive list of common pitfalls when using `outputs`.

From 36eacbdd88238d755af38bbda6c01e7f318852da Mon Sep 17 00:00:00 2001
From: Christian Roth <code@christianroth.dev>
Date: Wed, 1 May 2024 22:00:21 +0200
Subject: [PATCH 2/3] update README

---
 README.md | 3 ++-
 1 file changed, 2 insertions(+), 1 deletion(-)

diff --git a/README.md b/README.md
index cc0f3d96f5..ca9d183041 100644
--- a/README.md
+++ b/README.md
@@ -25,7 +25,8 @@ If you have questions or need help, please check out our documentation for a [li
     Run the following commands.
     - `conda env create -f ./.ci_scripts/environment.yml`
     - `conda activate conda-forge-docs`
-    - For live builds, `npm install && npm run start`
+    - enable pre-commit hooks with `pre-commit install`
+    - For live builds, `npm install && npm run start` - you can view the docs at `http://localhost:3000`
     - For production builds, run `.ci_scripts/update_docs`
 4.  Make and commit your changes.
 5.  Submit a [pull request](https://docs.github.com/en/github/collaborating-with-issues-and-pull-requests/about-pull-requests) to the main repository proposing your changes.

From 939bfbd435b0ed1e2e5c57ceb02a7e4ad10a3366 Mon Sep 17 00:00:00 2001
From: Christian Roth <code@christianroth.dev>
Date: Wed, 1 May 2024 22:16:16 +0200
Subject: [PATCH 3/3] Mark pre-commit instructions optional

Co-authored-by: jaimergp <jaimergp@users.noreply.github.com>
---
 README.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/README.md b/README.md
index ca9d183041..ca529afbee 100644
--- a/README.md
+++ b/README.md
@@ -25,7 +25,7 @@ If you have questions or need help, please check out our documentation for a [li
     Run the following commands.
     - `conda env create -f ./.ci_scripts/environment.yml`
     - `conda activate conda-forge-docs`
-    - enable pre-commit hooks with `pre-commit install`
+    - Optional. Enable pre-commit hooks with `pre-commit install`.
     - For live builds, `npm install && npm run start` - you can view the docs at `http://localhost:3000`
     - For production builds, run `.ci_scripts/update_docs`
 4.  Make and commit your changes.