doc/src/installation: document rolling-release model

[0xda157]

this has been a consistent issue people have been running into and reporting bugs about (e.g. #2114), so we should probably warn people in the documentation.

---

• I certify that I have the right to submit this contribution under the MIT license
• Commit messages adhere to Stylix commit conventions
• Theming changes adhere to the Stylix style guide
• Changes have been tested locally
• Changes have been tested in testbeds
• Each commit in this PR is suitable for backport to the current stable branch

[trueNAHO]

What about this:

From b237060bae07d0e55ed0db5a37379ac48027ee3b Mon Sep 17 00:00:00 2001
From: NAHO <[email protected]>
Date: Tue, 6 Jan 2026 00:16:58 +0100
Subject: [PATCH] doc/src/installation: note master branch follows
 rolling-release model

Note that the master branch follows a rolling-release model, as version
mismatches are a common source of issues.

Link: https://github.com/nix-community/stylix/pull/2116

Co-authored-by: 0xda157 <[email protected]>
---
 doc/src/installation.md | 10 ++++++++++
 1 file changed, 10 insertions(+)

diff --git a/doc/src/installation.md b/doc/src/installation.md
index d86b9171..1463f2e2 100644
--- a/doc/src/installation.md
+++ b/doc/src/installation.md
@@ -1,5 +1,15 @@
 # Installation

+> [!IMPORTANT]
+> The master (unstable) branch of Stylix follows a rolling-release model. To
+> ensure compatibility, all inputs must be kept in sync.
+>
+> Avoid partial updates and always update inputs together with:
+>
+> ```console
+> nix flake update
+> ```
+
 ## NixOS

 You can install Stylix into your NixOS configuration using [Flakes][nix-flakes].
--
2.51.2

This is what this looks like:

[trueNAHO]

LGTM.

Since the rolling-release model applies to all branches, should we make it more generic:

> Stylix follows a rolling-release model. To ensure compatibility, all inputs
> must be kept in sync.

Also, we might want to add the word "version" in the second sentence:

> Stylix follows a rolling-release model. To ensure version compatibility, all
> inputs must be kept in sync.

-- #2116 (comment)

I rebased this PR on top of master and applied those changes. Feel free to merge this PR if those changes are fine with you.

[0xda157]

Suggested change

	> Stylix follows a rolling-release model. To ensure version compatibility, all
	> Stylix follows a rolling-release model on the `master` (default) branch. To ensure version compatibility, all

[trueNAHO]

Does this not revert the following:

Since the rolling-release model applies to all branches, should we make it more generic:

> Stylix follows a rolling-release model. To ensure compatibility, all inputs
> must be kept in sync.

IMHO, it would be better to keep this more generic because the rolling-release model applies to all branches.

[0xda157]

Does this not revert the following:

Since the rolling-release model applies to all branches, should we make it more generic:

> Stylix follows a rolling-release model. To ensure compatibility, all inputs
> must be kept in sync.

it does

IMHO, it would be better to keep this more generic because the rolling-release model applies to all branches.

does /release-.*/ follow a rolling-release model? to my understanding we want to avoid breaking changes on those branches, to match what nixpkgs and home-manger do.