From e0f0e16c086cdae2b8149aa915c3b8b9844aea06 Mon Sep 17 00:00:00 2001
From: Jitka Halova <jobselko@redhat.com>
Date: Tue, 28 Apr 2026 09:58:09 +0200
Subject: [PATCH] Add docs for package policies

Assisted By: Claude Opus 4.6
---
 docs/user/guides/_SUMMARY.md                  |  2 +-
 .../{blocklist.md => package_policies.md}     | 53 +++++++++++++++----
 2 files changed, 45 insertions(+), 10 deletions(-)
 rename docs/user/guides/{blocklist.md => package_policies.md} (55%)

diff --git a/docs/user/guides/_SUMMARY.md b/docs/user/guides/_SUMMARY.md
index b92c4aca..d9c01bdb 100644
--- a/docs/user/guides/_SUMMARY.md
+++ b/docs/user/guides/_SUMMARY.md
@@ -4,4 +4,4 @@
 * [Host Python Content](host.md)
 * [Vulnerability Report](vulnerability_report.md)
 * [Attestation Hosting](attestation.md)
-* [Package Blocklist](blocklist.md)
+* [Package Policies](package_policies.md)
diff --git a/docs/user/guides/blocklist.md b/docs/user/guides/package_policies.md
similarity index 55%
rename from docs/user/guides/blocklist.md
rename to docs/user/guides/package_policies.md
index 81feaa3b..43b75b27 100644
--- a/docs/user/guides/blocklist.md
+++ b/docs/user/guides/package_policies.md
@@ -1,10 +1,8 @@
-# Package Blocklist
+# Package Policies
 
-A repository can have a blocklist that prevents specific packages from being added.
-Blocklist entries can match by package `name` (all versions), package `name` with an exact `version`, or exact `filename`.
-Exactly one of `name` or `filename` must be provided.
-
-Each entry records the PRN of the user who created it in the `added_by` field.
+Python repositories offer two mechanisms for controlling which packages they accept:
+**blocklists** to prevent specific packages from being added, and
+**package substitution control** to prevent silent replacement of existing packages.
 
 ## Setup
 
@@ -21,7 +19,15 @@ PULP_API="http://localhost:5001"
 REPO_HREF=$(pulp python repository show --name foo | jq -r ".pulp_href")
 ```
 
-## Add a blocklist entry
+## Package Blocklist
+
+A repository can have a blocklist that prevents specific packages from being added.
+Blocklist entries can match by package `name` (all versions), package `name` with an exact `version`, or exact `filename`.
+Exactly one of `name` or `filename` must be provided.
+
+Each entry records the PRN of the user who created it in the `added_by` field.
+
+### Add a blocklist entry
 
 === "By name (all versions)"
 
@@ -50,7 +56,7 @@ Set the UUID of a created entry for use in the subsequent commands:
 ENTRY_UUID=$(http GET "${PULP_API}${REPO_HREF}blocklist_entries/" | jq -r '.results[0].prn | split(":") | .[-1]')
 ```
 
-## List blocklist entries
+### List blocklist entries
 
 List all entries for a repository:
 
@@ -64,10 +70,39 @@ Show a single entry:
 http GET "${PULP_API}${REPO_HREF}blocklist_entries/${ENTRY_UUID}/"
 ```
 
-## Remove a blocklist entry
+### Remove a blocklist entry
 
 ```bash
 http DELETE "${PULP_API}${REPO_HREF}blocklist_entries/${ENTRY_UUID}/"
 ```
 
 Once an entry is removed, packages matching it can be added to the repository again.
+
+## 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).
+
+### 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.