docs: note VCS ignore interaction with packages (#10831)

[SarthakB11]

Refs #10831.

What

Adds a short warning block to the packages subsection of docs/pyproject.md explaining that files matched by VCS ignore settings (e.g. .gitignore) are excluded from the built distributions even when their parent directory is listed under packages, and points readers to exclude and include for the include-with-format workaround.

Why

On #10831 the reporter listed a generated-code directory under packages but had the same directory in .gitignore, and poetry build silently produced empty sdist/wheel archives. @dimbleby correctly pointed out that the behaviour is documented in the exclude and include subsection, but the reporter noted (and I agree) that the packages subsection itself does not mention the cross-talk — which is exactly where a user going from "I want to include this directory" to "my build is empty" lands first.

Quoting the reporter's refined ask on 2026-04-09:

However, the documentation for packages does not mention this cross-talk with the version control. If this is intended behaviour, I suggest putting a warning there, similar to that in the exclude-and-include section.

Diff

 Thus, you only have to specify the directory where your root package resides.
 {{% /note %}}
 
+{{% warning %}}
+If a VCS is being used, files matched by its ignore settings (for example by
+`.gitignore` for git) are excluded from the built distributions even when their
+parent directory is listed under `packages`. This can be surprising if a
+`packages` entry points at generated code or another path that is intentionally
+kept out of version control. To ship such files, add them back via
+[`include`]({{< relref "#exclude-and-include" >}}) with an explicit `format`.
+{{% /warning %}}
+
 ### exclude and include

No code change, no behaviour change — docs-only, 9 lines added.

[sourcery-ai]

Hey - I've found 1 issue, and left some high level feedback:

• Consider tightening the warning text to split the long sentence into two (e.g. one for the VCS-ignore behavior and a second for the generated-code scenario) to improve readability and make the key behavior easier to scan.

Prompt for AI Agents

Please address the comments from this code review:

## Overall Comments
- Consider tightening the warning text to split the long sentence into two (e.g. one for the VCS-ignore behavior and a second for the generated-code scenario) to improve readability and make the key behavior easier to scan.

## Individual Comments

### Comment 1
<location path="docs/pyproject.md" line_range="702-705" />
<code_context>

+{{% warning %}}
+If a VCS is being used, files matched by its ignore settings (for example by
+`.gitignore` for git) are excluded from the built distributions even when their
+parent directory is listed under `packages`. This can be surprising if a
+`packages` entry points at generated code or another path that is intentionally
</code_context>
<issue_to_address>
**nitpick (typo):** Consider adding a comma after "for example" and capitalizing "Git".

You could rephrase to something like "(for example, by `.gitignore` for Git)" so that "for example" is followed by a comma and the VCS name is capitalized.

```suggestion
{{% warning %}}
If a VCS is being used, files matched by its ignore settings (for example, by
`.gitignore` for Git) are excluded from the built distributions even when their
parent directory is listed under `packages`. This can be surprising if a
```
</issue_to_address>

---

Sourcery is free for open source - if you like our reviews please consider sharing them ✨

• X
• Mastodon
• LinkedIn
• Facebook

_{Help me be more useful! Please click 👍 or 👎 on each comment and I'll use the feedback to improve your reviews.}