From d719d4b1158cb41f278626740bfb1d6b1900afa2 Mon Sep 17 00:00:00 2001
From: jtrakk <43392409+jtrakk@users.noreply.github.com>
Date: Mon, 2 Mar 2020 18:53:44 -0800
Subject: [PATCH] Rename secondary "tests" package in doc example

If multiple distributions have `tests` as a top-level package, they'll conflict whenever both are installed. (Examples [here]((https://github.com/python-poetry/poetry/issues/1905) and [here](https://github.com/NixOS/nixpkgs/issues/81482). Two common alternative strategies are:

1. not distributing tests (as [here](https://github.com/pypa/sampleproject)), or
2. placing tests in a subdirectory of the main package, rather than adjacent (as [here](http://blog.habnab.it/blog/2013/07/21/python-packages-and-you/) and [here](http://as.ynchrono.us/2007/12/filesystem-structure-of-python-project_21.html)). Each of these strategies will avoid this issue.

Users may fall into this trap because of the [package documentation](https://python-poetry.org/docs/pyproject/#packages) page, which gives an example:

```
packages = [
    { include = "my_package" },
    { include = "tests", format = "sdist" },
]
```

Having two top-level packages in a distribution is relatively unusual, but does have some use cases.  Using `"tests"` as a top-level package name in the example is likely to lead to conflicts, however. The alternate package in the documentation example could have a unique name like `"my_other_package"`, which would reduce the likelihood of this kind of overlap.
---
 docs/docs/pyproject.md | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/docs/docs/pyproject.md b/docs/docs/pyproject.md
index b6bcbe318f1..7c2ffd2152e 100644
--- a/docs/docs/pyproject.md
+++ b/docs/docs/pyproject.md
@@ -127,11 +127,11 @@ it by using `format`:
 # ...
 packages = [
     { include = "my_package" },
-    { include = "tests", format = "sdist" },
+    { include = "my_other_package", format = "sdist" },
 ]
 ```
 
-From now on, only the `sdist` build archive will include the `tests` package.
+From now on, only the `sdist` build archive will include the `my_other_package` package.
 
 !!!note