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

Author: jenstroeger

.gitignore

@@ -27,6 +27,7 @@ share/python-wheels/
 .installed.cfg
 *.egg
 MANIFEST
+PKG-INFO
 
 # Local venv
 bin/

Makefile

@@ -186,7 +186,7 @@ dist: dist/$(PACKAGE_NAME)-$(PACKAGE_VERSION)-py3-none-any.whl dist/$(PACKAGE_NA
 dist/$(PACKAGE_NAME)-$(PACKAGE_VERSION)-py3-none-any.whl: check test-all dist/$(PACKAGE_NAME)-$(PACKAGE_VERSION)-build-epoch.txt
 	SOURCE_DATE_EPOCH=$(SOURCE_DATE_EPOCH) python -m flit build --setup-py --format wheel
 dist/$(PACKAGE_NAME)-$(PACKAGE_VERSION).tar.gz: check test-all dist/$(PACKAGE_NAME)-$(PACKAGE_VERSION)-build-epoch.txt
-	SOURCE_DATE_EPOCH=$(SOURCE_DATE_EPOCH) python -m flit build --setup-py --format sdist
+	SOURCE_DATE_EPOCH=$(SOURCE_DATE_EPOCH) python -m flit build --no-setup-py --format sdist
 dist/$(PACKAGE_NAME)-$(PACKAGE_VERSION)-docs-html.zip: docs-html
 	python -m zipfile -c dist/$(PACKAGE_NAME)-$(PACKAGE_VERSION)-docs-html.zip docs/_build/html/
 dist/$(PACKAGE_NAME)-$(PACKAGE_VERSION)-docs-md.zip: docs-md

README.md

@@ -22,6 +22,7 @@ This repository is intended to be a base template, a cookiecutter for a new Pyth
 [Generating documentation](#generating-documentation)  
 [Synchronizing with this template repo](#synchronizing-with-this-template-repo)  
 [Versioning, publishing and changelog](#versioning-publishing-and-changelog)  
+ [Building from a source distribution package](#building-from-a-source-distribution-package)  
 [Build integrity using SLSA framework](#build-integrity-using-slsa-framework)  
 [Cleaning up](#cleaning-up)  
 [Frequently asked questions](#frequently-asked-questions)  
@@ -268,7 +269,7 @@ In order to build a distribution of your package locally instead of publishing i
 make dist
 ```
 
-This builds a source package and a binary distribution, and stores the files in your local `dist/` folder.
+This builds a source package ([sdist](https://packaging.python.org/en/latest/discussions/package-formats/#what-is-a-source-distribution)) and a binary distribution ([wheel](https://packaging.python.org/en/latest/discussions/package-formats/#what-is-a-wheel)), and stores the files in your local `dist/` folder.
 
 You can also generate a changelog and bump the version manually and locally using commitizen (already installed as a dev dependency), for example:
 
@@ -277,6 +278,27 @@ cz changelog
 cz bump
 ```
 
+## Building from a source distribution package
+
+The source distribution package ([sdist](https://packaging.python.org/en/latest/discussions/package-formats/#what-is-a-source-distribution)) contains everything needed in order to check, test, and build a binary distribution ([wheel](https://packaging.python.org/en/latest/discussions/package-formats/#what-is-a-wheel)) and its documentation; that is particulalry useful for third-party packaging services that build their own software distribution packages using custom processes.
+
+To build from a source distribution package, simply follow these steps:
+
+```bash
+tar zxvf package.tar.gz  # Unpack the sdist tar file.
+cd package/
+git init  # We need this to be a Git repository to run checks.
+git add .  # Add all files so tools find them via the VCS.
+```
+
+We do need to initialize the package folder as a Git repository to ensure the Makefile is able to call various checkers via hooks. Once done, we can use `make` as before:
+
+```bash
+SKIP=check-hooks-apply,check-useless-excludes,actionlint make dist
+```
+
+Note that we skip Git hooks that are unnecessary when building from the source distribution. As above, this builds the source package and a binary distribution, and stores both in the  `dist/` folder. And, as expected, setting the `SOURCE_DATE_EPOCH` environment variable to the build epoch value of the original sdist and wheel build results in the bit-exact same binary distribution package!
+
 ## Build integrity using SLSA framework
 
 The build process in this repository follows the requirements in the [SLSA framework](https://slsa.dev/) to be compliant at level 3. An important aspect of SLSA to improve the supply chain security posture is to generate a verifiable provenance for the build pipeline. Such a provenance can be used to verify the builder and let the consumers check the materials and configurations used while building an artifact. In this repository we use the [generic provenance generator reusable workflow](https://github.com/slsa-framework/slsa-github-generator) to generate a provenance that can attest to the following artifacts in every release:

pyproject.toml

@@ -121,23 +121,16 @@ omit = [
 ]
 
 
-# https://flit.pypa.io/en/latest/pyproject_toml.html#sdist-section
+# https://flit.pypa.io/en/stable/pyproject_toml.html#sdist-section
 # See also: https://github.com/pypa/flit/issues/565
+# See also: https://github.com/pypa/flit/discussions/745
 [tool.flit.sdist]
 include = []
 exclude = [
     ".github/",
     ".vscode/",
-    "docs/",
-    "tests/",
-    ".flake8",
     ".gitattributes",
-    ".gitignore",
-    ".pre-commit-config.yaml",
-    "CHANGELOG.md",
     "CODEOWNERS",
-    "Makefile",
-    "SECURITY.md",
 ]