fix: the generated sdist file should contain everything needed to check and test the code, and to build the documentation as well

[jenstroeger]

This change supersedes PR #948 based on discussion pypa/flit#745, and contributes to PR #952.

The generated sdist file now contains these files:

> tar -ztvf dist/package-2.16.0.tar.gz
-rw-r--r-- 0/0            1883 2025-07-01 06:30 package-2.16.0/.flake8
-rw-r--r-- 0/0            5035 2025-07-01 06:30 package-2.16.0/.pre-commit-config.yaml
-rw-r--r-- 0/0            1063 2025-07-01 06:30 package-2.16.0/LICENSE.md
-rw-r--r-- 0/0           11471 2025-07-01 06:30 package-2.16.0/Makefile
-rw-r--r-- 0/0           28836 2025-07-01 06:30 package-2.16.0/README.md
-rw-r--r-- 0/0             675 2025-07-01 06:30 package-2.16.0/docs/Makefile
-rw-r--r-- 0/0            2006 2025-07-01 06:30 package-2.16.0/docs/source/conf.py
-rw-r--r-- 0/0             816 2025-07-01 06:30 package-2.16.0/docs/source/index.rst
-rw-r--r-- 0/0            8226 2025-07-01 06:30 package-2.16.0/pyproject.toml
-rw-r--r-- 0/0             386 2025-07-01 06:30 package-2.16.0/src/package/__init__.py
-rw-r--r-- 0/0             496 2025-07-01 06:30 package-2.16.0/src/package/__main__.py
-rw-r--r-- 0/0              80 2025-07-01 06:30 package-2.16.0/src/package/py.typed
-rw-r--r-- 0/0             520 2025-07-01 06:30 package-2.16.0/src/package/something.py
-rw-r--r-- 0/0             615 2025-07-01 06:30 package-2.16.0/tests/conftest.py
-rw-r--r-- 0/0             686 2025-07-01 06:30 package-2.16.0/tests/test_something.py
-rw-r--r-- 0/0            1352 1970-01-01 10:00 package-2.16.0/setup.py
-rw-r--r-- 0/0           31320 1970-01-01 10:00 package-2.16.0/PKG-INFO

This is essentially a git archive of the folder allowing somebody to build the package and documentation, to run all code checks, and to run the tests.

However, because this generated archive is not a git folder but our development process assumes both git and pre-commit, the archive doesn’t quite work out of the box. I think it would be ok to remove Makefile and .pre-commit-config.yaml, and let the user figure out the rest?

Tagging @takluyver

[takluyver]

I think most of your Makefile is usable without a git repo - and even pre-commit config can be used by creating a new blank git repo (that's really what pre-commit maintainers suggest 🤷 ). So I'd be inclined to leave them in the sdist. But it's definitely a matter of taste, once you go beyond the tests & docs that downstream packagers typically expect. 🙂

[jenstroeger]

I think most of your Makefile is usable without a git repo - and even pre-commit config can be used by creating a new blank git repo (that's really what pre-commit maintainers suggest 🤷 ).

So, it takes a tad more to make this work on a folder unpacked from a git archive.

After unpacking the archived repository — as the thread hints — we need to git init the repo and we also need to git add all the existing files to make pre-commit work (otherwise it won’t know of any files).

[jenstroeger]

@behnazh @takluyver I finally got around to this PR again. Following Thomas’s advice the sdist now contains everything needed build a wheel (and another sdist).

Furthermore, by setting SOURCE_DATE_EPOCH (docs) we’re able to produce a wheel from the sdist:

/tmp/sdist/package-2.18.0 > md5sum dist/package-2.18.0.tar.gz dist/package-2.18.0-py3-none-any.whl 
4310f1af61875f87d41a190aa15a85ac  dist/package-2.18.0.tar.gz
defaca1183be751636599c050ca5ce05  dist/package-2.18.0-py3-none-any.whl

that’s bit-exactly the same wheel as the original built from the source repository:

~/opt/dev/python-package-template > md5sum dist/package-2.18.0.tar.gz dist/package-2.18.0-py3-none-any.whl 
0f06a8346c1ca3ce20b1fa11f16c0bed  dist/package-2.18.0.tar.gz
defaca1183be751636599c050ca5ce05  dist/package-2.18.0-py3-none-any.whl

The sdist files do not match, however, because “reproducible” applies to wheels only.