From aef519de98c17056f88a02da3b3caf5cb0491e36 Mon Sep 17 00:00:00 2001
From: Alexey Martemyanov <mallexxx@gmail.com>
Date: Tue, 6 Oct 2026 14:21:10 +0600
Subject: [PATCH] [2026-10-06] eagle:
 work/notes/webkit-macos-version-mapping.md

---
 work/notes/webkit-macos-version-mapping.md | 80 ++++++++++++++++++++++
 1 file changed, 80 insertions(+)
 create mode 100644 work/notes/webkit-macos-version-mapping.md

diff --git a/work/notes/webkit-macos-version-mapping.md b/work/notes/webkit-macos-version-mapping.md
new file mode 100644
index 00000000..c97a99ca
--- /dev/null
+++ b/work/notes/webkit-macos-version-mapping.md
@@ -0,0 +1,80 @@
+---
+title: WebKit release → macOS version mapping
+tags: [webkit, safari, macos, reference]
+created: 2026-10-06
+source: ~/Downloads/WebKit_sparse (git checkout of github.com/WebKit/WebKit, main @ 99051d5d08)
+---
+
+# WebKit release → macOS version mapping
+
+## TL;DR
+Готовой опубликованной таблицы «релиз WebKit → macOS-релиз» не существует.
+Маппинг **выводится из исходников** — он в самом дереве WebKit, а не на сайте.
+
+## Механизм (ground truth)
+
+AppleWebKit-версия в User-Agent собирается из двух частей:
+
+```
+AppleWebKit = SYSTEM_VERSION_PREFIX (зависит от macOS) + FULL_VERSION WebKit
+```
+
+### 1. macOS → SYSTEM_VERSION_PREFIX
+
+Файл: `Configurations/Version.xcconfig`, строки 35–53.
+
+| macOS | SYSTEM_VERSION_PREFIX |
+|---|---|
+| 15 Sequoia | 20 |
+| 16 | 21 |
+| 26 Tahoe | 21 |
+| 27 Golden Gate | 22 |
+| 28 | 23 |
+| 29 | 24 |
+| 30 | 25 |
+| (default) | 22 |
+
+### 2. FULL_VERSION WebKit (текущий main)
+
+`Configurations/Version.xcconfig`:
+- MAJOR = 627, MINOR = 1, TINY = 2 → FULL_VERSION = `627.1.2`
+
+### Пример сборки UA-токена
+
+| macOS | prefix | AppleWebKit/… |
+|---|---|---|
+| 15 Sequoia | 20 | `20627.1.2` |
+| 16 | 21 | `21627.1.2` |
+| 26 Tahoe | 21 | `21627.1.2` |
+| 27 Golden Gate | 22 | `22627.1.2` |
+| 30 | 25 | `25627.1.2` |
+
+> Примечание: префиксы 21 у macOS 16 и 26 — это одно и то же системное поколение нумерации, отсюда совпадение.
+
+## Что есть в дереве
+
+| Что | Путь | Содержимое |
+|---|---|---|
+| macOS → prefix + текущая версия | `Configurations/Version.xcconfig` | таблица префиксов + MAJOR/MINOR/TINY |
+| macOS ↔ кодовые имена | `Tools/Scripts/webkitpy/common/version_name_map.py` | Leopard … Tahoe, Golden Gate |
+| таймлайн релизов WebKit | `git log Configurations/Version.xcconfig` | коммиты «Versioning. WebKit-XXXX.Y.Z» |
+| отгруженные релизы | `git ls-remote --heads origin` | 498 веток `safari-XXXX-branch` |
+| генератор deployment target | `Configurations/Scripts/generate-deployment-target-xcconfig.py` | 6-значные minor-версии → semver |
+
+## Чего в дереве НЕТ
+Готовой таблицы «релиз WebKit → macOS-релиз». Она собирается из трёх источников:
+1. prefix-таблица (в дереве, `Version.xcconfig`);
+2. Apple Safari/iOS release notes — какая версия вошла в какой macOS;
+3. `git log Configurations/Version.xcconfig` — таймлайн бампов версии.
+
+## Источники (проверено)
+- Файл: `~/Downloads/WebKit_sparse/Configurations/Version.xcconfig` — 76 строк, 3640 байт.
+- Строки 35–53 — таблица префиксов и `SYSTEM_VERSION_PREFIX_macosx_*`.
+- Строки 24–29 — MAJOR/MINOR/TINY/FULL.
+- Источник: рабочий чекаут Alex (`WebKit_sparse`), не внешний сайт.
+
+## Pitfalls
+- Префикс `SYSTEM_VERSION_PREFIX_macosx_` (пустой) = `22` — это default для неизвестного macOS; не путать с реальным.
+- `Version.xcconfig` есть **только** в `Configurations/` (один файл); вложенных копий в `Source/` нет.
+- Sparse/shallow клоны содержат лишь ~10 последних бампов версии — полная история требует полного клона.
+- Ветки `origin` содержат `integration/...safari-XXX-branch` (мусор от CI) — фильтровать по чистому `^safari-[0-9.]*-branch$`.