From 3c3c7db0be0caea457df65c6987ac05b60239d1d Mon Sep 17 00:00:00 2001 From: Jens Troeger Date: Tue, 1 Jul 2025 06:33:30 +1000 Subject: [PATCH 1/4] fix: the generated sdist file should contain everything needed to check and test the code, and to build the documentation as well --- pyproject.toml | 8 ++------ 1 file changed, 2 insertions(+), 6 deletions(-) diff --git a/pyproject.toml b/pyproject.toml index 52c357f5..f3e5f633 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -121,22 +121,18 @@ 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", ] From 64be104e73ad7fbce8bbd28e2fbe0615fdd3e746 Mon Sep 17 00:00:00 2001 From: Jens Troeger Date: Tue, 7 Apr 2026 14:16:20 +1000 Subject: [PATCH 2/4] chore: make sdist round-trip reproducible wheels --- .gitignore | 1 + Makefile | 2 +- README.md | 23 ++++++++++++++++++++++- pyproject.toml | 1 - 4 files changed, 24 insertions(+), 3 deletions(-) diff --git a/.gitignore b/.gitignore index 89f1b2d5..962302b5 100644 --- a/.gitignore +++ b/.gitignore @@ -27,6 +27,7 @@ share/python-wheels/ .installed.cfg *.egg MANIFEST +PKG-INFO # Local venv bin/ diff --git a/Makefile b/Makefile index 8a59187c..d827b55d 100644 --- a/Makefile +++ b/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 diff --git a/README.md b/README.md index 14595542..c7b74d57 100644 --- a/README.md +++ b/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) @@ -266,7 +267,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: @@ -275,6 +276,26 @@ 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 a everything from a source distribution package, simply follow these steps: + +```bash +tar zxvf package.tar.gz # Unpack the tar file. +cd package/ +git init # We need this to be a Git repository to run checks. +``` + +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 both the source package and a binary distribution, and stores them in the `dist/` folder. In addition, 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: diff --git a/pyproject.toml b/pyproject.toml index f3e5f633..cb0aa8e9 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -130,7 +130,6 @@ exclude = [ ".github/", ".vscode/", ".gitattributes", - ".gitignore", "CHANGELOG.md", "CODEOWNERS", "SECURITY.md", From 0f059114cdbfb61bed4f07fccb921ce2cdaa2805 Mon Sep 17 00:00:00 2001 From: Jens Troeger Date: Tue, 7 Apr 2026 14:20:02 +1000 Subject: [PATCH 3/4] chore: keep SECURITY and CHANGELOG in the sdist for documentation purposes --- pyproject.toml | 2 -- 1 file changed, 2 deletions(-) diff --git a/pyproject.toml b/pyproject.toml index cb0aa8e9..5016ac29 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -130,9 +130,7 @@ exclude = [ ".github/", ".vscode/", ".gitattributes", - "CHANGELOG.md", "CODEOWNERS", - "SECURITY.md", ] From 283c9b3c1c78b7317c70935b83ed4dad6535478c Mon Sep 17 00:00:00 2001 From: Jens Troeger Date: Tue, 7 Apr 2026 14:36:18 +1000 Subject: [PATCH 4/4] chore: fix typos --- README.md | 7 ++++--- 1 file changed, 4 insertions(+), 3 deletions(-) diff --git a/README.md b/README.md index c7b74d57..34d48878 100644 --- a/README.md +++ b/README.md @@ -280,12 +280,13 @@ cz bump 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 a everything from a source distribution package, simply follow these steps: +To build from a source distribution package, simply follow these steps: ```bash -tar zxvf package.tar.gz # Unpack the tar file. +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: @@ -294,7 +295,7 @@ We do need to initialize the package folder as a Git repository to ensure the Ma 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 both the source package and a binary distribution, and stores them in the `dist/` folder. In addition, 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! +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