In order for our customers to have a FRAME machine which they can rely on, the FRAME needs to be shipped with software which our customers can rely on. We will ship software in two ways:

1. Software which we pre-load in the FRAME machine before delivery to customers.
2. Future software updates which the customers will download onto the FRAME, as described by ‣ ).

For either software delivery mechanism, the software should be:

• Well-understood by the software team: the software team needs to know exactly what software has shipped with each FRAME machine, so that we can help customers with troubleshooting any software problems they experience. Furthermore, the software team needs to know about problems in the software and ways for customers to mitigate or work around those problems until a fix can be delivered with a future software update.
• Of sufficiently high quality to be ready for customer use: while software bugs and problems are unavoidable, we should minimize the bugs we ship. This includes minimizing unexpected regressions, as well as doing enough software testing that we can minimize our rate of accidentally shipping new bugs which we don’t yet know about. Thus, we must thoroughly test any changes we make before we ship them to customers.
• Updated at a reasonable cadence: serious and urgent bugs should be fixed quickly in new software releases which should be delivered quickly. The delivery of those fixes should not be blocked by having to wait for other lower-priority/less-urgent improvements to be finished first.

This DN describes our process for planning and managing and executing new releases of all of our software so that we can deliver stable software releases to:

1. the production line which will load our software onto hardware (as discussed in ‣ )
2. customers who will download software updates directly onto their FRAME machines

Technical version identifiers

All software is version-controlled using Git, so that any version of our source code is identified with a Git commit hash. We will make certain commits easier to identify by giving them human-readable (developer-facing) technical version identifiers, i.e. technical version numbers. These version identifiers should communicate some information about the significance of the version, e.g. whether it’s a version which a customer should use or whether it’s only for internal testing.

Any software binary we provide to the customers (e.g. flashed SD cards, SD card images, Docker container images, firmware binaries) must be fully traceable back to a particular Git commit of our source code, so that we can determine the source code of whatever software is running in a customer machine. This means that we should try to minimize changes to binary which aren’t captured as changes to source code in a Git repository. For any such changes which we must make (e.g. as customer-specific or machine-specific config files, config variables in flash memoryo and/or EEPROM, etc.), we must be especially careful about recording exactly what changes we make. Being disciplined about recording that information is necessary in order to maintain the traceability and reproducibility of what we deliver to our customers.

openUC2 OS

openUC2 OS is a combination of many individual software components; some components (such as ImSwitch) are written, maintained, and distributed by openUC2, while other components (such as the Cockpit administration dashboard and the system file browser) are written, maintained, and distributed by other open-source software projects. Each component has its own release schedule and version numbering system; the specific combination of releases and versions of all these components will change over time as these components change, and we represent each total combination of all software components in a particular release of openUC2 OS by a single version number assigned to that release.

For releases of openUC2 OS, we use a calendar-based version numbering system with three numeric components and an optional pre-release suffix. Specifically:

• For stable releases (i.e. generally-available customer releases, as opposed to testing pre-releases) the version number is a string of the format v(year).(notable).(hotfix), where the year, notable, and hotfix components are each non-negative integers. For example, v26.0.0 and v27.2.1 could both be valid version strings for releases, while v26-0-0 and v26.0 and v26 would not be valid version strings for releases.
  • hotfix is incremented by 1 for a new release which consists only of small but important bug fixes (which we call “hotfixes”). For example, if there were some small bugs in v26.0.0 (where hotfix is 0) which we wanted to patch urgently, then we could publish those patches as a v26.0.1 hotfix release (where hotfix is now 1).
  • notable is incremented by 1 for a new release which includes any notable changes larger than hotfixes; such changes may be backwards-compatible or backwards-incompatible. For example, if our first notable release was v26.0.0 (where notable is 0) and then we wanted to make a second notable release in 2026 which added a new feature (without any backwards-incompatible changes), that second release would be v26.1.0 (where notable is 1). If we then wanted to make a third notable release in 2026 which made a backwards-incompatible API change, then its version number would be v26.2.0 (where notable is 2).
  • year is a number representing number of years (in the Gregorian calendar) after 2000 in which the notable release is (or will be) published. In the terminology of Calendar Versioning, this number is a YY-formatted year. For example, version v26.0.0 (where year is 26) represents the first notable release to be published in 2026 and v26.1.0 represents the second notable release to be published in 2026, while version v27.0.0 (where year is 2027) represents the first notable release to be published in 2027. Version v101.0.0 would represent the first notable release to be published in 2126. We use YY format instead of YYYY format because YYYY format makes version strings difficult to say out loud. Also, it’s easier to switch from YY-formatted CalVer strings to SemVer strings because the major component of the resulting version numbers won’t look like a year in the future.
  • These numeric components must not contain leading zeroes. For example, v26.0.0 and v26.1.0 are allowed, while v26.01.0 is not allowed.
  • At least one component must increase numerically in a new release. For example, v26.1.0 → v26.2.0 is an allowed sequence of version numbers for successive releases, while v26.2.0 → v26.1.0 is not an allowed sequence.
    • hotfix must be reset to 0 when notable is incremented. For example, v26.1.1 → v26.2.0 is an allowed sequence of version numbers for successive releases, while v26.1.1 → v26.2.1 is not allowed.
    • Both hotfix and notable must be reset to 0 when year is incremented. For example, v26.2.1 → v27.0.0 is an allowed sequence of version numbers for successive releases, while v26.2.1 → v27.2.0 and v26.2.1 → v27.0.1 both are not allowed.
    • year should not be changed for hotfix releases published the year after the notable release which they were based on. For example, if v27.2.0 were published in December 2027 and then we wanted to publish a hotfix for it in January 2028, then we would call it v27.2.1, not v28.0.0.
    • year must be changed for notable releases published the year after the previous notable release. For example, if v27.2.0 were published in December 2027 and then we wanted to publish a notable release based on it in March 2028, then we would call it v28.0.0, not v27.3.0.
• For pre-releases intended for testing ahead of a stable release: The version number is a string of the format v(year).(notable).(hotfix)-(modifier), where v(year).(notable).(hotfix) represents the planned stable release which the pre-release is intended for, and modifier is an additional string included to identify the type of pre-release.
  • We typically publish multiple "alpha" and "beta" pre-releases with additional improvements before a stable release, so modifier has the format of either alpha.(index) or beta.(index), where index is a non-negative integer with no leading zeroes. For example, the first "alpha" pre-release for v26.0.0 was v26.0.0-alpha.0, the second "alpha" pre-release was v26.0.0-alpha.1, and the first "beta" pre-release will be v26.0.0-beta.0.
  • When we switch from alpha to beta, index must be reset to 0. For example, v26.0.0-alpha.1 → v26.0.0-beta.0 is an allowed sequence of version numbers for successive pre-releases, while v26.0.0-alpha.1 → v26.0.0-beta.0 is not allowed.
• Once a versioned release has been published, the contents of that version must not be modified. Instead, any modifications must be released as a new version.
• Due to Hyrum’s Law (as well as the large surface-area of exposed interfaces in openUC2 OS, which includes HTTP APIs, CLI APIs, systemd services, Forklift feature flags, etc., which are all potentially subject to backwards-incompatible changes), we cannot promise ahead-of-time that any release (whether notable or hotfix) will be completely backwards-compatible for all users. This is the key semantic difference between the three numeric components (major, minor, patch) in Semantic Versioning’s version numbers versus the three numeric components (year, notable, hotfix) in openUC2 OS’s version numbers.
  • While for Semantic Versioning a “patch release” means that all included bugfixes are strictly backwards-compatible, for openUC2 OS a hotfix release just means that all included bugfixes are small enough and important enough that we think all customers should upgrade quickly, and that we expect (but cannot always promise) that none of the bugfixes will cause backwards-incompatible changes to officially-supported functionalities. Even though we cannot promise full backwards-compatibility, we still should make our best effort to minimize any backwards incompatibilities.
  • In general it should be safe and easy for the customer to perform an in-place upgrade (using the in-place upgrade mechanisms described in ‣, as opposed to reflashing the machine’s SD card for openUC2 OS) from the current release to a new hotfix release based on it. It should also be safe and easy for the customer to roll back from their upgrade to the new hotfix release (using the in-place rollback mechanisms described in ‣ ). Any changes which require SD card reflashing or which are impossible to roll back should be published as a notable release rather than a hotfix release.
  • While Semantic Versioning distinguishes between backwards-compatible changes (with its minor component) and backwards-incompatible changes (with its major component), our versioning scheme does not make such distinctions. Any notable release of openUC2 OS (i.e. any release which increments our year or notable components) should be considered as being like a “major release” in the terminology of Semantic Versioning. Even a hotfix release might include a backwards-incompatible change (though we should do our best to avoid including backwards-incompatible changes in hotfix releases).