doc/src/installation: note master branch follows 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 <90870942+trueNAHO@users.noreply.github.com>
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 <da157@voidq.com>
---
 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.

[trueNAHO]

On a side note, it would be great to document our backport policy somewhere so it can be linked in the following:

stylix/.github/PULL_REQUEST_TEMPLATE.md

Line 16 in 3894cae

- [ ] Each commit in this PR is suitable for backport to the current stable branch

[stylix-automation]

Successfully created backport PR for release-25.11:

• [release-25.11] doc/src/installation: note master branch follows rolling-release model  #2175