Document what flit_core includes in a sdist

[pfmoore]

In the docs it notes that building via a frontend other than flit includes a "minimal" set of files needed to build the sdist. Please could the docs be amended to include the exact settings for [tool.flit.sdist] to replicate flit_core's behaviour?

Having the docs specify settings needed to get the default flit_core behaviour everywhere would make it easier to set up a consistent sdist build workflow that didn't rely on which build frontend was used.

The alternative is to review and explicitly choose exactly what files to include. This is feasible, but risks omitting something important either by accident or from ignorance. Having "what flit considers the minimal requirement" documented reduces that risk. (To be fair, the minimum is probably just "pyproject.toml and the project source directory" but explicit is better than implicit, as they say 😉)

[takluyver]

That's actually more of a feature request 🙂 - there's currently no simple setting to disable the use of git/hg to determine what goes in the sdist. You would have to make exclusion patterns for all the extra files that are checked in but aren't needed, which I don't think there's an easy way to do in general.

#522 is (in part) a more general discussion about this discrepancy between flit_core and the flit command.

[pfmoore]

I'd assumed that if I added an exclude pattern to exclude everything, and then added in what I wanted, that would work the way I was after. But I now see that the docs say "Exclusions have priority over inclusions", which sort of wrecks that idea 🙁

So there's currently no way to make flit not pull in everything that's in VCS without manually maintaining a bunch of exclude lines? I'm particularly thinking of things like the .github directory, .gitignore, .pre-commit-config.yaml and the like. That's a shame. (I realise it doesn't matter that much in the grand scheme of things, but I like my sdists to be clean source archives, whereas VCS for me is "what I use to work on the project").

I got the feeling that "VCS is the master list of what to include" was a rather fundamental principle for flit, so I was resigned to flit not being a good fit for me, but when I saw that flit_core didn't do that I was quite excited. But maybe it's less of a change in philosophy than a temporary technical discrepancy...

I guess I'll keep an interested eye on #522 and see how that works out. Thanks for the pointer.

[takluyver]

I haven't entirely changed philosophy, but my view wasn't compatible with PEP 517's take on sdists, and I haven't resolved that. I focused on the thing you upload to PyPI, which I wanted to be a full snapshot of the project's development state, even including CI config. If the VCS history was lost (e.g. if the hosting service shut down), you could continue development from the latest sdist on PyPI, and even make a coarse history in a new repository by committing each release.

[pfmoore]

Thinking about this some more, I still think that it needs to be documented what flit_core will include. It's not at all obvious at the moment - it seems to do what I'd expect in simple cases (package named the same as the project, either in the root directory or in a src subdirectory), but it's not at all obvious what will happen if you go beyond that.

As far as I can see, what gets included is:

1. pyproject.toml
2. LICENSE (it doesn't seem to allow a .txt or .md extension...)
3. Either <project>.py, or a directory called <project> or src/<project>, whichever is present. Only one is allowed.

Is that right? And if it is, can it be added to the docs so that it's discoverable without experimenting (and worrying if there's anything I missed 😉).

If you confirm it's correct, I'll happily create a docs PR to add it.

[takluyver]

That's almost right, but in point 2 it should include license & readme files referenced in pyproject.toml (e.g. PEP 621 project.license.file), regardless of their extensions. There's no automatic inclusion based on filenames for this.

(Plus, of couse, it can include extra files based on config under tool.flit.sdist)