From 879343c71098171f9bd83545ca3ef99c8ca22fd5 Mon Sep 17 00:00:00 2001
From: John Preston <johnprestonmail@gmail.com>
Date: Wed, 8 Jul 2026 00:14:40 +0400
Subject: [PATCH] [ai] Forbid Q_OS_LINUX checks in the agent guidelines

---
 AGENTS.md | 23 +++++++++++++++++++++++
 REVIEW.md | 21 +++++++++++++++++++++
 2 files changed, 44 insertions(+)

diff --git a/AGENTS.md b/AGENTS.md
index c87ae5fec8..83d4d5c026 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -241,6 +241,29 @@ auto text = u"Settings"_q;
 auto text = QStringLiteral("Settings");
 ```
 
+**Never use `Q_OS_LINUX` for platform checks in new code:**
+
+Telegram Desktop distinguishes at most three platforms: Windows / macOS / all-other. The "all-other" branch covers Linux, the BSD variants and more — and this is almost always the branch you want. `Q_OS_LINUX` narrows it to Linux alone, silently excluding the non-Linux Unix platforms, which is almost never intended. For the all-other branch use `!defined Q_OS_WIN && !defined Q_OS_MAC` at compile time, or its runtime equivalent `Platform::IsLinux()` — which, despite the name, means exactly `!defined Q_OS_WIN && !defined Q_OS_MAC` ("everything except Windows and macOS"), not Linux specifically:
+
+```cpp
+// BAD - excludes FreeBSD and other non-Linux Unix:
+#ifdef Q_OS_LINUX
+UnixSpecificCode();
+#endif // Q_OS_LINUX
+
+// GOOD - the all-other branch, compile time:
+#if !defined Q_OS_WIN && !defined Q_OS_MAC
+UnixSpecificCode();
+#endif // !Q_OS_WIN && !Q_OS_MAC
+
+// GOOD - the all-other branch, runtime (same meaning, NOT Linux-only):
+if (Platform::IsLinux()) {
+	UnixSpecificCode();
+}
+```
+
+`Q_OS_LINUX` is only for the rare case where you genuinely want exactly Linux and not the other Unix-like systems — usually you don't. The few existing uses (`Telegram/SourceFiles/core/sandbox.cpp`, `Telegram/SourceFiles/platform/linux/specific_linux.cpp`) are such genuinely Linux-only code paths and stay as-is.
+
 ## API Usage
 
 ### API Schema Files
diff --git a/REVIEW.md b/REVIEW.md
index d1a9a646dd..7c7da7e5a8 100644
--- a/REVIEW.md
+++ b/REVIEW.md
@@ -553,3 +553,24 @@ Non-static member functions use camelCase (`startBatch`, `finalize`). Static mem
 // GOOD - PascalCase for static method:
 [[nodiscard]] static bool ShouldTrack(not_null<HistoryItem*> item);
 ```
+
+## No Q_OS_LINUX platform checks in new code
+
+Telegram Desktop distinguishes at most three platforms: Windows / macOS / all-other, where "all-other" covers Linux, the BSD variants and more — and this is almost always the branch that is wanted. A `Q_OS_LINUX` check narrows it to Linux alone, silently excluding the non-Linux Unix platforms, which is almost never intended. For the all-other branch use `!defined Q_OS_WIN && !defined Q_OS_MAC` at compile time, or its runtime equivalent `Platform::IsLinux()` — which, despite the name, means exactly `!defined Q_OS_WIN && !defined Q_OS_MAC` ("everything except Windows and macOS"), not Linux specifically. `Q_OS_LINUX` is only for the rare case where exactly Linux is meant and not the other Unix-like systems — usually it is not. The few existing uses (`Telegram/SourceFiles/core/sandbox.cpp`, `Telegram/SourceFiles/platform/linux/specific_linux.cpp`) are such genuinely Linux-only code paths and stay as-is.
+
+```cpp
+// BAD - excludes FreeBSD and other non-Linux Unix:
+#ifdef Q_OS_LINUX
+UnixSpecificCode();
+#endif // Q_OS_LINUX
+
+// GOOD - the all-other branch, compile time:
+#if !defined Q_OS_WIN && !defined Q_OS_MAC
+UnixSpecificCode();
+#endif // !Q_OS_WIN && !Q_OS_MAC
+
+// GOOD - the all-other branch, runtime (same meaning, NOT Linux-only):
+if (Platform::IsLinux()) {
+	UnixSpecificCode();
+}
+```