From ad26c35abe3f9dcb54b153f7ceb78dc91b173801 Mon Sep 17 00:00:00 2001
From: Jitka Halova <jobselko@redhat.com>
Date: Thu, 23 Apr 2026 11:17:30 +0200
Subject: [PATCH 1/2] Add docs for package substitution

Assisted By: Claude Opus 4.6
---
 docs/user/guides/_SUMMARY.md             |  1 +
 docs/user/guides/package_substitution.md | 43 ++++++++++++++++++++++++
 2 files changed, 44 insertions(+)
 create mode 100644 docs/user/guides/package_substitution.md

diff --git a/docs/user/guides/_SUMMARY.md b/docs/user/guides/_SUMMARY.md
index b92c4aca..231fee5d 100644
--- a/docs/user/guides/_SUMMARY.md
+++ b/docs/user/guides/_SUMMARY.md
@@ -5,3 +5,4 @@
 * [Vulnerability Report](vulnerability_report.md)
 * [Attestation Hosting](attestation.md)
 * [Package Blocklist](blocklist.md)
+* [Package Substitution](package_substitution.md)
diff --git a/docs/user/guides/package_substitution.md b/docs/user/guides/package_substitution.md
new file mode 100644
index 00000000..bfb2bca7
--- /dev/null
+++ b/docs/user/guides/package_substitution.md
@@ -0,0 +1,43 @@
+# Package Substitution
+
+By default, Python repositories allow package substitution: uploading, syncing, or adding a package
+with the same filename as an existing package but a different checksum will silently replace it.
+
+This behavior is controlled by the `allow_package_substitution` field on a Python repository.
+When set to `False`, any operation (upload, sync, or modify) that would replace an existing package with a different checksum is rejected.
+Re-adding a package with the same filename *and* the same checksum is always accepted (idempotent).
+
+## Setup
+
+If you do not already have a repository, create one:
+
+```bash
+pulp python repository create --name foo
+```
+
+Set the API base URL and repository HREF for use in the subsequent commands:
+
+```bash
+PULP_API="http://localhost:5001"
+REPO_HREF=$(pulp python repository show --name foo | jq -r ".pulp_href")
+```
+
+## Disable package substitution
+
+```bash
+http PATCH "${PULP_API}${REPO_HREF}" allow_package_substitution=false
+```
+
+You can also set this when creating a repository:
+
+```bash
+http POST "${PULP_API}/pulp/api/v3/repositories/python/python/" name="bar" allow_package_substitution=false
+```
+
+## Re-enable package substitution
+
+```bash
+http PATCH "${PULP_API}${REPO_HREF}" allow_package_substitution=true
+```
+
+Once re-enabled, packages with duplicate filenames can replace existing content again.

From 21033f0ec0b523a651b691c7095f903f782d2745 Mon Sep 17 00:00:00 2001
From: Jitka Halova <jobselko@redhat.com>
Date: Thu, 23 Apr 2026 11:33:27 +0200
Subject: [PATCH 2/2] Sort docs alphabetically

---
 docs/user/guides/_SUMMARY.md | 8 ++++----
 1 file changed, 4 insertions(+), 4 deletions(-)

diff --git a/docs/user/guides/_SUMMARY.md b/docs/user/guides/_SUMMARY.md
index 231fee5d..eef7b0a0 100644
--- a/docs/user/guides/_SUMMARY.md
+++ b/docs/user/guides/_SUMMARY.md
@@ -1,8 +1,8 @@
+* [Attestation Hosting](attestation.md)
+* [Host Python Content](host.md)
+* [Package Blocklist](blocklist.md)
+* [Package Substitution](package_substitution.md)
 * [Set up your own PyPI](pypi.md)
 * [Sync from Remote Repositories](sync.md)
 * [Upload and Manage Content](upload.md)
-* [Host Python Content](host.md)
 * [Vulnerability Report](vulnerability_report.md)
-* [Attestation Hosting](attestation.md)
-* [Package Blocklist](blocklist.md)
-* [Package Substitution](package_substitution.md)