[proposal] New patcher config

Add design proposal for new patcher configuration.

See: #939
Signed-off-by: Christian Heimes <cheimes@redhat.com>

Author: tiran

docs/index.rst

@@ -76,6 +76,7 @@ Contributing to fromager.
    :maxdepth: 2
 
    develop.md
+   proposals/index.rst
 
 What's with the name?
 ---------------------

docs/proposals/index.rst

@@ -0,0 +1,7 @@
+Fromager Enhancement Proposals
+==============================
+
+.. toctree::
+   :maxdepth: 1
+
+   new-patcher-config

docs/proposals/new-patcher-config.md

@@ -0,0 +1,121 @@
+# New patching configuration
+
+- Author: Christian Heimes
+- Created: 2026-02-26
+- Status: Open
+
+## What
+
+This enhancement document proposes a new approach to patch sources and wheel
+metadata through declarative configuration. The new feature supplements
+current features like patch files and plugin hooks.
+
+## Why
+
+Fromager supports patch files and modifications with Python plugins. Patch
+files are limited, because they either apply to a single version or to all
+versions of a package. Python plugins are harder to write and take more
+effort.
+
+Fromager already supports limited patching of `pyproject.toml` with the
+package setting option `project_override`.
+
+## Goals
+
+- provide simple, extensible patching facilities with a declarative
+  configuration approach
+- support version-specific patching (e.g. patch build system requirements for
+  `>=1.0,<1.0`).
+- make common tasks like fixing sdist metadata (`PKG-INFO`) easier
+- enable patching of wheel and sdist package metadata so users can pin
+  installation requirements (`requires-dist`) to constraints. The feature is
+  designed to pin Torch version to ensure `libtorch` ABI compatibility.
+
+## Non-goals
+
+- patch files will not be deprecated and removed. Patches are still useful
+  and will be supported in the future.
+- CPU architecture-specific and variant-specific patches won't be supported,
+  They are considered a misfeature. Patches should be architecture-
+  independent, so they can be pushed to upstream eventually.
+- patching of installation requirements (`requires-dist`) beyond pinning to
+  constraints. Dependency issues should be fixed in upstream projects.
+
+## How
+
+The new system will use a new top-level configuration key `patch`, which is
+an array of patch operations. Each patch operation has a title, optional
+version specifier, and an action like `replace-line`, `fix-pkg-info`, or
+`pyproject-build-system`.
+
+- The action name acts as a tag ([discriminated union](https://docs.pydantic.dev/latest/concepts/unions/#discriminated-unions)).
+- The `title` is a human-readable description that explains the purpose of
+  the operation.
+- The optional field `when_version` can be used to limit the action,
+  e.g. `>=1.0,<2.0`.
+  > **NOTE**: `when_version` is not compatible with nightly builds.
+- Some actions have a `ignore_missing` boolean flag. If an action has no
+  effect, then it fails and stops the build unless `ignore_missing` is set.
+- All file names are relative to `sdist_root_dir`.
+- Most patch actions are executed in `prepare_source` phase. Actions that
+  affect `requires-dist` are run in `get_install_dependencies_of_sdist`
+  and after `build_wheel` hook.
+
+### Example actions
+
+At first, we will implement a few patch actions that will cover the most
+common cases. In the future, we may add additional patch actions.
+
+- The `replace-line` action replaces lines in one or more files.
+
+- The `delete-line` action removes a line from one or more files.
+
+- The `pyproject-build-system` action replaces the old `project_override`
+  settings `update_build_requires` and `remove_build_requires`.
+
+- The `fix-pkg-info` action addresses issues with sdist's `PKG-INFO` files,
+  e.g. wrong metadata version.
+
+- The `pin-requires-dist-to-constraint` action pins `requires-dist` in sdist
+  and wheel metadata to the values of global constraints. The primary use
+  case is Torch. If a package is built with Torch 2.10.0 constraint, then
+  we want the wheel to depend on exactly `torch==2.10.0`.
+
+```yaml
+patch:
+  - title: Comment out 'foo' requirement for version >= 1.2
+    action: replace-line
+    files:
+      - 'requirements.txt'
+    search: '^(foo.*)$'
+    replace: '# \\1'
+    when_version: '>=1.2'
+    ignore_missing: true
+
+  - title: Remove 'bar' from constraints.txt
+    action: delete-line
+    files:
+      - 'constraints.txt'
+    search: 'bar.*'
+
+  - title: Fix PKG-INFO metadata and update metadata version
+    action: fix-pkg-info
+    metadata_version: '2.4'
+    when_version: '<1.0'
+
+  - title: Add missing setuptools to pyproject.toml
+    action: pyproject-build-system
+    update_build_requires:
+      - setuptools
+
+  - title: Pin Torch to global constraint
+    action: pin-requires-dist-to-constraint
+    requirements:
+     - torch
+```
+
+### Deprecations
+
+The old settings `project_override.update_build_requires` and
+`project_override.remove_build_requires` will be deprecated and eventually
+removed.