Releases

Edge Releases

These releases do not contain any SLA or semantic versioning guarantees, but we will announce breaking changes in the Changelog.

While these releases will get the latest features, they will also have an increased rate of bugs and other problems. As a result, we do not recommend using edge releases in production environments without using PanfactumPlus.

This framework maintains a strictly linear history. Bug fixes and new features will be added in new releases only (i.e., they will never be back-ported).

Edge Release Format

Edge releases will be of the format:

edge.<YY>-<MM>-<DD>

Edge Release Cadence

We have no set cadence for the edge releases, but we generally release 2-5 times per month.

Stable Releases

Stable releases will receive patches for significant bugs or security vulnerabilities for six (6) months following its initial release.

For example, version stable.25-04.X will receive support until the end of October 2025. If you need support for a longer period, you should consider signing up for PanfactumPlus.

“Significant” will be determined by a combination of the following criteria:

  • Does it impact the recommended way to utilize the framework?

  • Does it create a clear impairment of intended functionality or a clear security vulnerability for users of the framework?

If the answer to both of these questions is “yes,” then it is likely that we will:

  • We will attempt to resolve the issue within 30 days

  • We will patch supported releases

Stable Release Format

Each release will be of the format:

stable.<YY>-<MM>.<patch_number>

For example, stable.25-04.5 represents the fifth patch to the stable version released in April 2025.

While this deviates from the normal practice of many open source projects which tend to use semantic versioning, we do this for good reasons:

  • The framework is not a standalone utility, but rather a packaging of 100s of utilities that all work together. Regardless of whether new functionality is added, we MUST update our component systems regularly to keep up with the ecosystems that we target (e.g., Kubernetes). In many ways, it resembles a package registry like nixpkgs. We take inspiration from these registries which have time-based vs. functionality-based release names.

  • With time-based releases, every release should be considered a major release with functionality changes that consumers should review for potential breaking changes. This could be conveyed using an integer for a major version number (e.g., 1, 2, 3, etc.). However, we can do better: the version timecode <YY>-<MM>. This retains the sortable property of integers, but adds additional contextual information that reflects our time-based release practices.

  • The version timecode allows users to immediately know whether that version is still officially supported by Panfactum maintainers. See the support policy below.

  • We additionally provide a patch number for when we backport bug fixes to previous releases. While we could simply update each <YY>-<MM> release directly, a patch number provides the following benefits:

    • Many utilities use caches and/or lockfiles. Even if we update branch <YY>-<MM>, there is no guarantee that you would receive the new updates (e.g., flake.lock would prevent this with nix flakes). Providing a patch ensures that those caches and/or lockfiles would receive the new code.

    • There are several automations such as renovate or dependabot that will notify you if code changes, but only if you cut a new discrete release number. For critical items like security patches, we want our users to be able to receive notifications if they should update immediately.

Stable Release Cadence

We aim to align the creation of new stable release channels with new releases of Kubernetes as that is the central component in the Panfactum framework. That means new stable releases roughly three times per year.

We strongly recommend that users of the Panfactum framework update to new stable release channels within three months.

We strongly recommend that patch versions of the Panfactum stack are applied immediately. We only create new patches if there are significant fixes for bugs or security vulnerabilities.

We endeavor to never introduce breaking changes in patches. If a fix requires breaking functionality, we will cut a new stable release channel.