Versions and Upgrades

The framework publishes SemVer 🡕 versions. A version is what your project pins, what the documentation describes, and what you read on a deployed host.

The version contract

While the framework is in 0.x, it is the MINOR number that carries the breaking changes. The PATCH number never carries any.

Number	What changes	Examples
0.Y.z (minor)	Breaking change	etc/config.yaml key renamed, darkone.* option removed, just recipe renamed, usr/ structure modified
0.y.Z (patch)	Nothing to migrate	fix, new module or service, new option, nixpkgs bump

Version 1.0.0 will mark the public launch. From then on, it will be the MAJOR number that carries the breaking changes.

Always read the changelog before upgrading

Each breaking change is described in a ⚠ Breaking section of the CHANGELOG 🡕, with the broken surface and the migration to perform.

Pinning a version

A consumer project declares the framework by its tag, and commits its flake.lock. Without this file, a clone of the project rebuilds a different tree every time.

flake.nix

inputs = {
  dnf.url = "github:darkone-linux/darkone-nixos-framework/v0.1.0";
};

The generator does not need to be declared: the pinned framework version mechanically fixes the version of the generator that goes with it.

Upgrading the version

1. Spot the target version in the releases 🡕 and read the ⚠ Breaking sections of all versions traversed.

2. Modify the tag in flake.nix, then refresh the lock:

   nix flake update dnf

3. Point the dnf/ link back to the revision the lock pins:

   nix run .#init

4. Regenerate, check, then deploy a test host before the fleet:

   just generate
   just apply-local test

5. Commit flake.nix and flake.lock together.

Try without committing

To build against a version without touching the project:

nixos-rebuild switch --flake .#<hôte> \
  --override-input dnf github:darkone-linux/darkone-nixos-framework/<tag>

Knowing what runs on a host

Each deployed host carries its version, which avoids guessing after a rollback or a fleet updated host by host.

cat /etc/dnf-release
nixos-version

/etc/dnf-release gives the published version (DNF_RELEASE) and the exact git revision (DNF_REV). nixos-version shows the version as a dnf-X.Y.Z label, also visible in the boot entries.

Projects that go together

Project	Version rule
darkone-nixos-framework	Reference, this is what you pin
dnf-generator	Own version, pinned by the framework
dnf-doc	Shares MAJOR.MINOR with the framework
dnf-boilerplate, dnf-example	Mirror tag of the framework, committed lock

To read the documentation that matches your version, compare the MAJOR.MINOR: the 0.1.x doc describes the 0.1.x framework.