diff --git a/Makefile b/Makefile index edfbc68b..dbbf83bd 100644 --- a/Makefile +++ b/Makefile @@ -197,6 +197,19 @@ dist/$(PACKAGE_NAME)-$(PACKAGE_VERSION)-docs-md.zip: docs-md dist/$(PACKAGE_NAME)-$(PACKAGE_VERSION)-build-epoch.txt: echo $(SOURCE_DATE_EPOCH) > dist/$(PACKAGE_NAME)-$(PACKAGE_VERSION)-build-epoch.txt +# Build a PEP-503 compatible Simple Repository directory inside of dist/. For details on +# the layout of that directory and the normalized project name, see: https://peps.python.org/pep-0503/ +# The directory can then be used to install (hashed) artifacts by using `pip` and +# its `--extra-index-url` argument: https://pip.pypa.io/en/stable/cli/pip_install/#cmdoption-extra-index-url +PROJECT_NAME := $(shell python -c $$'import re; print(re.sub(r"[-_.]+", "-", "$(PACKAGE_NAME)").lower());') +.PHONY: simple-index +simple-index: dist/$(PACKAGE_NAME)-$(PACKAGE_VERSION)-py3-none-any.whl dist/$(PACKAGE_NAME)-$(PACKAGE_VERSION).tar.gz + mkdir -p dist/simple-index/$(PROJECT_NAME) + echo -e "\nSimple Index$(PACKAGE_NAME)" > dist/simple-index/index.html + echo -e "\nSimple Index: $(PROJECT_NAME)$(PACKAGE_NAME)-$(PACKAGE_VERSION)-py3-none-any.whl$(PACKAGE_NAME)-$(PACKAGE_VERSION).tar.gz" > dist/simple-index/$(PROJECT_NAME)/index.html + cp -f dist/$(PACKAGE_NAME)-$(PACKAGE_VERSION)-py3-none-any.whl dist/simple-index/$(PROJECT_NAME)/ + cp -f dist/$(PACKAGE_NAME)-$(PACKAGE_VERSION).tar.gz dist/simple-index/$(PROJECT_NAME)/ + # Build the HTML and Markdown documentation from the package's source. DOCS_SOURCE := $(shell git ls-files docs/source) .PHONY: docs docs-html docs-md diff --git a/README.md b/README.md index 8add8a90..7d77de8c 100644 --- a/README.md +++ b/README.md @@ -21,8 +21,9 @@ This repository is intended to be a base template, a cookiecutter for a new Pyth [Testing](#testing) [Generating documentation](#generating-documentation) [Synchronizing with this template repo](#synchronizing-with-this-template-repo) -[Versioning, publishing and changelog](#versioning-publishing-and-changelog) +[Versioning, publishing and distributions](#versioning-publishing-and-distributions)  [Building from a source distribution package](#building-from-a-source-distribution-package) + [Using the Simple Index](#using-the-simple-index) [Build integrity using SLSA framework](#build-integrity-using-slsa-framework) [Cleaning up](#cleaning-up) [Frequently asked questions](#frequently-asked-questions) @@ -255,7 +256,7 @@ In addition to the default HTML, Sphinx also generates Markdown documentation co The [sync-with-upstream.yaml](https://github.com/jenstroeger/python-package-template/blob/main/.github/workflows/sync-with-upstream.yaml) GitHub Acions workflow checks this template repo daily and automatically creates a pull request in the downstream repo if there is a new release. Make sure to set up the GitHub username and email address in this workflow accordingly. -## Versioning, publishing and changelog +## Versioning, publishing and distributions To enable automation for [semantic versioning](https://semver.org/), package publishing, and changelog generation it is important to use meaningful [conventional commit messages](https://www.conventionalcommits.org/)! This package template already has a built-in semantic release support enabled which is set up to take care of all three of these aspects — every time changes are pushed to the `release` branch. @@ -299,6 +300,16 @@ 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! +## Using the Simple Index + +Once source and/or binary distribution packages have been built, they can be served using a [PEP 503](https://peps.python.org/pep-0503/) compatible package repository. Simply call + +```bash +make simple-index +``` + +to create the package repository in the `dist/` folder, and then use it e.g. with [pip](https://pip.pypa.io/en/stable/cli/pip_install/#cmdoption-extra-index-url) and its `--extra-index-url` parameter. + ## 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: