From ce689f8d577ec45c1ff7c92a828c56cd194d8d5d Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Randy=20D=C3=B6ring?=
 <30527984+radoering@users.noreply.github.com>
Date: Sun, 6 Oct 2024 18:12:29 +0200
Subject: [PATCH 1/4] docs: improve explanation of `exclude` and `include`

---
 docs/pyproject.md | 31 +++++++++++++++++--------------
 1 file changed, 17 insertions(+), 14 deletions(-)

diff --git a/docs/pyproject.md b/docs/pyproject.md
index 39b7b192253..7cb13602fcf 100644
--- a/docs/pyproject.md
+++ b/docs/pyproject.md
@@ -622,12 +622,20 @@ Poetry is clever enough to detect Python subpackages.
 Thus, you only have to specify the directory where your root package resides.
 {{% /note %}}
 
-### include and exclude
+### exclude and include
 
-A list of patterns that will be included in the final package.
+A list of patterns that will be excluded or included in the final package.
+
+```toml
+[tool.poetry]
+# ...
+exclude = ["my_package/excluded.py"]
+include = ["my_package/data.txt"]
+```
 
 You can explicitly specify to Poetry that a set of globs should be ignored or included for the purposes of packaging.
 The globs specified in the exclude field identify a set of files that are not included when a package is built.
+`include` has priority over `exclude`.
 
 If a VCS is being used for a package, the exclude field will be seeded with the VCS’ ignore settings (`.gitignore` for git for example).
 
@@ -635,12 +643,6 @@ If a VCS is being used for a package, the exclude field will be seeded with the
 Explicitly declaring entries in `include` will negate VCS' ignore settings.
 {{% /note %}}
 
-```toml
-[tool.poetry]
-# ...
-include = ["CHANGELOG.md"]
-```
-
 You can also specify the formats for which these patterns have to be included, as shown here:
 
 ```toml
@@ -648,17 +650,18 @@ You can also specify the formats for which these patterns have to be included, a
 # ...
 include = [
     { path = "tests", format = "sdist" },
-    { path = "for_wheel.txt", format = ["sdist", "wheel"] }
+    { path = "my_package/for_sdist_and_wheel.txt", format = ["sdist", "wheel"] }
 ]
 ```
 
-If no format is specified, `include` defaults to only `sdist`.
+If no format is specified, it will default to include both `sdist` and `wheel`.
 
-In contrast, `exclude` defaults to both `sdist` and `wheel`.
+{{% warning %}}
+When a wheel is installed, its includes are unpacked straight into the `site-packages` directory.
+Pay attention to include top level files and directories with common names like
+`CHANGELOG.md`, `LICENSE`, `tests` or `docs` only in sdists and **not** in wheels.
+{{% /warning %}}
 
-```toml
-exclude = ["my_package/excluded.py"]
-```
 
 ### dependencies and dependency groups
 

From 54befc7c48ac8a0f08ca378d0a2f8d1039e95cfe Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Randy=20D=C3=B6ring?=
 <30527984+radoering@users.noreply.github.com>
Date: Fri, 11 Oct 2024 17:21:48 +0200
Subject: [PATCH 2/4] adapt explanation and examples to changed default

---
 docs/pyproject.md | 6 ++++--
 1 file changed, 4 insertions(+), 2 deletions(-)

diff --git a/docs/pyproject.md b/docs/pyproject.md
index 7cb13602fcf..00d5abd5752 100644
--- a/docs/pyproject.md
+++ b/docs/pyproject.md
@@ -630,7 +630,7 @@ A list of patterns that will be excluded or included in the final package.
 [tool.poetry]
 # ...
 exclude = ["my_package/excluded.py"]
-include = ["my_package/data.txt"]
+include = ["CHANGELOG.md"]
 ```
 
 You can explicitly specify to Poetry that a set of globs should be ignored or included for the purposes of packaging.
@@ -654,7 +654,9 @@ include = [
 ]
 ```
 
-If no format is specified, it will default to include both `sdist` and `wheel`.
+If no format is specified, `include` defaults to only `sdist`.
+
+In contrast, `exclude` defaults to both `sdist` and `wheel`.
 
 {{% warning %}}
 When a wheel is installed, its includes are unpacked straight into the `site-packages` directory.

From 6cdb9a4e97782394f65516ab339cf4de55ada5d9 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Randy=20D=C3=B6ring?=
 <30527984+radoering@users.noreply.github.com>
Date: Wed, 16 Oct 2024 17:42:10 +0200
Subject: [PATCH 3/4] use ref that includes python-poetry/poetry-core#773

---
 poetry.lock | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/poetry.lock b/poetry.lock
index 8bef0cfed76..f4ecaa7be66 100644
--- a/poetry.lock
+++ b/poetry.lock
@@ -1003,7 +1003,7 @@ develop = false
 type = "git"
 url = "https://github.com/python-poetry/poetry-core.git"
 reference = "main"
-resolved_reference = "beb93b1aba6ad47667c05721a74c8f3961402046"
+resolved_reference = "eb68b291ccbb1ff226e04cdd5a58acc6e6053c0a"
 
 [[package]]
 name = "pre-commit"

From 468b32e7453c759899834558f14da1df0e8c4ca1 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Randy=20D=C3=B6ring?=
 <30527984+radoering@users.noreply.github.com>
Date: Sun, 20 Oct 2024 17:38:27 +0200
Subject: [PATCH 4/4] add note about packages vs. include

---
 docs/pyproject.md | 5 +++++
 1 file changed, 5 insertions(+)

diff --git a/docs/pyproject.md b/docs/pyproject.md
index 00d5abd5752..2377f68dd11 100644
--- a/docs/pyproject.md
+++ b/docs/pyproject.md
@@ -624,6 +624,11 @@ Thus, you only have to specify the directory where your root package resides.
 
 ### exclude and include
 
+{{% note %}}
+If you just want to include a package or module, which is not picked up automatically,
+use [packages]({{< relref "#packages" >}}) instead of `include`.
+{{% /note %}}
+
 A list of patterns that will be excluded or included in the final package.
 
 ```toml