Support and compatibility¶

This page is for anyone deciding whether prodockit fits a project or checking whether their platform and tool versions are covered. It describes the public support and compatibility boundary; implementation-specific constraints remain in Contributor internals.

Maturity and stability¶

prodockit is currently classified as Alpha and uses pre-1.0 versions. Its document features and publishing tools are functional and tested, but there is not yet a formal, versioned public API stability contract. A pre-1.0 upgrade can therefore include a breaking change when the change is needed to make the public configuration consistent. Such changes are identified in the release notes.

The future stability contract is tracked in issue #7.

Required versions¶

Installing prodockit installs these Python dependencies automatically:

The current test matrix covers Python 3.10, 3.11, 3.12, and Python 3.13. The documentation build currently pins Zensical 0.0.55 and pymdown-extensions 11.0.1 so changes to either renderer arrive as reviewed version changes rather than silently altering published output.

PyMdown Blocks is particularly important when evaluating the authoring model. The numbered-steps and directory-tree extensions are specialised Blocks API implementations, so their slash fences, nesting rules, and option layout follow PyMdown's block syntax. They are not separate parsers that only resemble it.

Pandoc, WeasyPrint, Node tools, fonts, and other optional publishing requirements depend on the output being built. See Installation for that complete tool-by-tool boundary.

Platforms and test depth¶

The platform testing described here covers Linux, macOS, and Windows. Bootstrap has now completed manual end-to-end testing on Ubuntu Linux, Windows, and macOS against both the University of Surrey's GitLab (gitlab.surrey.ac.uk) and GitHub.com.

Two complete document workflows were exercised:

1. Start a new document: prepare the machine with bootstrap, create a new document repository on the selected host, and reach a working local build.
2. Adopt an existing document: take an existing online repository, install it locally on the prepared machine, and reach a working local build.

This is practical integration testing across the three operating systems, two hosts, and both common starting points. It verifies that the stages work together in real environments, beyond unit tests or inspection of generated commands. It is not an automated cross-platform regression matrix, however:

The manual matrix gives confidence in installation and first-use integration, but it is a point-in-time result. The locally run macOS suite adds full regression coverage on that platform, although it is not enforced by a hosted pull-request gate. Windows can still regress between manual runs because it does not yet run the full suite for every change.

Windows requires native libraries for PDF generation that pip cannot install. It also uses different default text encodings. The known setup steps are documented under PDF requirements, and prodockit bootstrap checks the corresponding tools. Report a Windows-only failure rather than assuming it is local configuration; it may expose a real coverage gap.

Bootstrap also recognises GitLab.com, but the completed manual platform matrix described above covers Surrey GitLab and GitHub.com. See Set up a machine for the host boundary.

Supported surfaces¶

For observable constraints such as live-reload staleness, unsupported citation forms, and differences between browser and PDF rendering, see Known limitations. If the behaviour is not listed there, search or open a GitHub issue.

Upgrade safely¶

Read the release notes before changing a pinned version. Build the site with zensical build --clean --strict, build the PDF if the project publishes one, and run its built-output checks before merging. Template-based projects should also review changes reported by template-sync.