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..34d48878 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,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: diff --git a/pyproject.toml b/pyproject.toml index 52c357f5..5016ac29 100644 --- a/pyproject.toml +++ b/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", ]