Первоисточник против пересказа: как дойти до места, где написана правда

Вопрос: обязан ли HTTP-клиент повторять запрос при получении ответа 503?

Три ответа, которые вы получите за одинаковое время:

• Из статьи в блоге: «на 503 нужно ретраить с экспоненциальной задержкой». Звучит разумно.
• Из ответа на Q&A-площадке: «зависит от вашей задачи, но обычно да». Тоже звучит разумно.
• Из спецификации: 503 означает, что сервер временно не может обработать запрос; сервер МОЖЕТ прислать Retry-After; ничего про обязанность клиента повторять там не сказано, зато сказано про идемпотентность методов, и это меняет вопрос целиком.

Разница не в том, что первые два ответа «неправильные». Разница в том, что они — рекомендации, а третий — контракт. Если вы строите систему, вам нужны оба, но путать их нельзя: на рекомендации нельзя опереться в споре, при отладке совместимости и при разборе инцидента.

Что такое первичный источник в инженерии

В историографии первичный источник — свидетельство очевидца. В инженерии определение удобнее сформулировать так:

Первичный источник — это текст, произведённый теми, кто отвечает за поведение системы, либо сама система.

Отсюда естественная градация, идущая от самого точного к самому дешёвому в чтении.

Ключевая мысль: разные уровни отвечают на разные вопросы, а не на один и тот же с разной точностью. Спецификация не расскажет, почему у вашего вендора это работает иначе. Исходники не расскажут, почему выбрали такой дизайн. Обсуждение расскажет почему, но не расскажет, что в релизе. Поэтому «идти к первоисточнику» — это не «всегда читать RFC», а «понимать, какой источник может ответить на этот вопрос».

Что теряется при пересказе

Пересказ — не обязательно ложь. Обычно это правда, из которой убрали пять вещей, и каждая из них однажды вам понадобится.

1. Модальность. В нормативных текстах есть разница между MUST, SHOULD и MAY (RFC 2119, уточнённый RFC 8174). Пересказ превращает всё в «нужно». Особенно вредно превращение SHOULD в MUST: SHOULD означает «можно отступить, полностью понимая последствия», а не «желательно». Языковую сторону нормативных документов подробно разбирает глава про спецификации и RFC.

2. Версия. В первоисточнике почти всегда написано, к какой версии относится утверждение. В пересказе — почти никогда. Через два года это превращает верное утверждение в ловушку.

3. Условия. «Гарантируется порядок» в оригинале звучит как «гарантируется порядок в пределах партиции при отключённых повторах и одном продюсере». Условия — первое, что вылетает при сокращении, и единственное, что имеет значение при отладке.

4. Границы применимости. Оригинал говорит «в наших измерениях на такой конфигурации»; пересказ говорит «X быстрее Y».

5. Контекст спора. Первоисточник часто содержит обсуждение альтернатив и причин отказа от них. Пересказ даёт вывод без аргументов — то есть ровно то, что бесполезно, когда ваша ситуация отличается.

К этому добавляется механизм, который делает всё хуже: пересказы пересказывают пересказы.

Ключевая деталь: на каждом шаге никто не врал. Каждый упрощал ровно чуть-чуть. Итоговое утверждение при этом не просто неточное — оно непроверяемое, потому что вместе с деталями исчезли ссылки.

Восхождение к источнику

Приём, который стоит довести до автоматизма. Занимает от одной до пяти минут.

Практические подсказки к каждому шагу.

• Ссылка есть, но ведёт на главную страницу документации. Это не ссылка. Ищите внутри по термину; если не находится — считайте, что источника нет.
• Ссылки нет. Возьмите самое необычное словосочетание из утверждения, поставьте в кавычки и поищите. Оригинал обычно старше и подробнее. Иногда обнаруживается, что «оригинал» — это пост на форуме 2014 года.
• Источник — чужая реализация. Реализация не является нормой. То, что библиотека X так делает, доказывает только, что X так делает.
• Источник — стандарт за деньгами. Часть стандартов (ISO, некоторые отраслевые) платные. Часто существует свободный эквивалент: черновик, зеркало у другого органа, спецификация того же механизма в открытом формате. Например, язык C описан стандартом ISO, но публичные черновики комитета в открытом доступе есть.

Где искать нормативные тексты

Не «как их читать» — про чтение есть глава в треке про обучение — а где они физически лежат и как искать по ним.

Три приёма, специфичных для нормативных текстов:

1. Проверьте шапку раньше содержания. Obsoletes, Updated by, статус документа. Ссылка на устаревший RFC в чужой статье — частый признак того, что статью не обновляли.
2. Ищите не по теме, а по нормативному слову. Запрос вида "MUST NOT" retry idempotent site:rfc-editor.org попадает прямо в нормативный абзац.
3. Смотрите errata. Опубликованные RFC не правят, ошибки живут в отдельном реестре rfc-editor.org/errata.

Changelog: самый недооценённый документ проекта

Если бы надо было выбрать один тип первичного источника, который окупается чаще всех, это был бы changelog.

Причина в том, что changelog — единственный документ, который отвечает на вопрос «когда». Документация описывает текущее состояние. Исходники описывают текущее состояние. Только список изменений говорит, что было раньше, что поменялось и в какой версии, — а именно это нужно, когда «у нас работало, а после обновления перестало».

Что там искать:

• Breaking changes — обычно вынесены отдельно. Читаются за минуту, экономят дни.
• Deprecations — что помечено устаревшим. Это карта того, куда движется проект, и предупреждение о будущей поломке.
• Изменения умолчаний. Самый коварный класс: код не менялся, поведение изменилось. Такие строчки выглядят безобидно: «default value of X changed from A to B».
• Исправления, совпадающие с вашим симптомом. Прямой способ узнать, что ваш баг уже починили в версии на две выше.

# у большинства проектов на GitHub список релизов доступен как лента
curl -s https://github.com/OWNER/REPO/releases.atom | rg -o '<title>[^<]+' | head -20

# сравнение двух версий чужого проекта: что вообще менялось
git clone --filter=blob:none https://github.com/OWNER/REPO && cd REPO
git log --oneline v1.4.0..v1.6.0 -- path/to/subsystem
git diff v1.4.0..v1.6.0 -- CHANGELOG.md

# что менялось в документации между версиями — часто информативнее кода
git diff v1.4.0..v1.6.0 -- docs/

Последняя команда — приём, который стоит запомнить: диффом документации между двумя версиями вы за минуту получаете список смысловых изменений, отфильтрованный авторами лучше, чем любым поиском.

Полезные конвенции, которые стоит знать, потому что они делают changelog пригодным для машинного чтения: Keep a Changelog и семантическое версионирование. Их соблюдение — само по себе сигнал о зрелости проекта. Про совместимость и эволюцию контрактов подробно — глава в треке принципов.

Issue-трекер: где живёт «почему»

Документация описывает результат. Трекер хранит спор, из которого этот результат родился.

Что искать в трекере и как:

# ваш симптом среди уже закрытого
repo:owner/name is:issue is:closed "connection reset by peer"

# самые обсуждаемые нерешённые проблемы — карта известных ограничений
repo:owner/name is:issue is:open sort:comments-desc

# что мейнтейнеры считают «работает как задумано»
repo:owner/name is:issue label:"wontfix" OR label:"working as intended"

# обсуждение конкретного изменения
repo:owner/name is:pr "default timeout"

Приём, который экономит больше всего времени: искать среди закрытых задач. Открытые — это список того, что ещё не сделано. Закрытые — это база знаний, в которой мейнтейнер уже объяснил, почему поведение именно такое.

Второй приём: от строки кода к обсуждению. Нашли в исходниках странное место — посмотрите, каким коммитом оно появилось, найдите номер PR в сообщении коммита, откройте обсуждение. Там будет написано, какую проблему это решало. Механика такого расследования — глава 6 и, более подробно про инструменты Git, Расследование по истории.

Вендорские источники, о которых забывают

• Security advisories. Официальные бюллетени содержат точный список затронутых версий и условий эксплуатации — то, чего нет в новостях об уязвимости.
• Страница статуса и её история инцидентов. Публичные постмортемы облачных провайдеров — первичный источник о том, как ведёт себя сервис при отказах. Читать их полезнее, чем маркетинговые страницы про надёжность. Про жанр — глава про постмортемы.
• Раздел ограничений и квот. Обычно спрятан, обычно отвечает на вопрос, который вы зададите через месяц.
• Матрица поддерживаемых версий и сроков поддержки. Отвечает на вопрос «до какого момента это вообще будет работать».
• Лицензия и её изменения. Смена лицензии проектом — событие, которое ломает планы; в первичном источнике оно датировано и обосновано.

Как отличить официальный источник от похожего на него

Вокруг любого популярного проекта вырастает слой сайтов, которые выглядят как документация, но ею не являются. Это не всегда злой умысел: чаще это старые зеркала, автоматические переводы и агрегаторы. Опасность одна и та же — вы читаете текст, который никто не обновлял.

Признаки, по которым источник опознаётся как официальный:

• Ссылка стоит в README репозитория проекта. Это самый надёжный тест: перейдите в репозиторий и посмотрите, куда ведёт ссылка на документацию оттуда.
• Домен упоминается в самом коде — в сообщениях об ошибках, в комментариях, в конфигурации сборки документации.
• Есть переключатель версий, и он работает. Документация без версии — либо «живая» спецификация, либо заброшенная копия.
• Есть ссылка «edit this page», ведущая в репозиторий. Значит, у документации есть история изменений, и её можно посмотреть.

Признаки копии:

• перевод без указания даты оригинала и без ссылки на него;
• домен, похожий на официальный, но с другим суффиксом;
• документация одной версии без возможности переключиться;
• реклама вокруг текста документации;
• контент, который дословно совпадает с официальным, но обрывается на середине разделов.

Практический приём: прежде чем читать незнакомый сайт документации, откройте её же исходники. Документация большинства проектов лежит в том же репозитории в каталоге docs/, и у неё есть коммиты. История файла отвечает на два вопроса сразу: насколько текст свежий и что в нём меняли.

Когда пересказ полезен

Было бы неверно вывести из главы «читайте только первоисточники». Вторичные тексты решают три задачи, которых первичные не решают:

1. Вход в незнакомую область. Спецификация не объясняет, зачем существует то, что она описывает. Хороший обзор даёт карту, по которой потом можно ходить.
2. Объяснение сложного. Автор, который потратил месяц на понимание, может сэкономить вам этот месяц.
3. Чужой опыт эксплуатации. Ни в какой спецификации не написано, что происходит с этим брокером на третий год работы под нагрузкой. Это знание существует только в рассказах людей.

Правило простое: пересказ — источник гипотез и объяснений, но не источник фактов о поведении системы. Гипотезу из статьи можно и нужно брать. Проверять её надо в первичном источнике или экспериментом.

Как быстро оценить качество вторичного текста, до того как читать:

Что записывать о найденном утверждении

Чтобы восхождение не пришлось повторять, у утверждения должна быть минимальная карточка. Модель данных здесь ровно такая:

Это не предложение заводить базу данных. Это перечень полей, без которых через полгода запись бесполезна: формулировка, ссылка с точным местом, версия, дата, тип источника и способ, которым вы это проверили. Как оформлять такие записи дёшево — глава 13; про заметки как внешнюю память вообще — соответствующая глава трека про обучение.

Сколько это стоит

Честный учёт, потому что восхождение не бесплатно.

Правило, к которому это сводится: чем дороже ошибка и чем дольше решение будет жить, тем выше по иерархии надо подниматься. Одноразовый скрипт не требует спецификации. Формат, в котором вы будете хранить данные пять лет, требует.

Типичные ошибки

1. Считать чужую реализацию нормой. «В библиотеке X так сделано» — это факт про X, а не про протокол.
2. Брать утверждение без версии. Без версии оно не истинно и не ложно, оно неопределённо.
3. Останавливаться на документации, когда вопрос нормативный. Документация вендора описывает его продукт, а не стандарт.
4. Не заглядывать в changelog при регрессии. Это первое место, а не последнее.
5. Читать только открытые issue. Ответы лежат в закрытых.
6. Путать «нет в документации» с «не поддерживается». Часто это значит только, что не задокументировано; исходники ответят точнее.
7. Верить ссылке, не открыв её. Ссылка на главную страницу документации ссылкой не является.

Мини-итог

• Первичный источник — тот, что произведён отвечающими за поведение системы, или сама система.
• Уровни отвечают на разные вопросы: исполняемое — что происходит, нормативное — что обязано, проектное — что намеревались, обсуждение — почему.
• При пересказе теряются модальность, версия, условия, границы и аргументы. Цепочка пересказов делает утверждение непроверяемым.
• Восхождение к источнику занимает минуты: ссылка → точное место → версия → сверка с вашим случаем.
• Changelog отвечает на вопрос «когда», которого нет ни в документации, ни в коде; дифф документации между версиями — быстрый способ увидеть смысловые изменения.
• Трекер хранит «почему»; искать надо среди закрытых задач.
• Пересказ полезен как вход в область, объяснение и чужой опыт, но не как источник фактов о поведении.
• У найденного утверждения должна быть карточка: формулировка, точная ссылка, версия, дата, тип источника, способ проверки.

Источники

• RFC 2119 (Bradner S., 1997) и RFC 8174 (Leiba B., 2017) — нормативные ключевые слова: rfc-editor.org/rfc/rfc2119, rfc-editor.org/rfc/rfc8174.
• RFC 9110, «HTTP Semantics», 2022 — актуальная семантика кодов ответа: rfc-editor.org/rfc/rfc9110.
• IETF Datatracker — история документов, черновики, связи между RFC: datatracker.ietf.org.
• The Open Group Base Specifications (POSIX) — pubs.opengroup.org.
• Keep a Changelog — keepachangelog.com; Semantic Versioning — semver.org.
• OSV — база уязвимостей с точным указанием затронутых диапазонов версий: osv.dev.

Что дальше

Первичный источник найден — и это чаще всего документация, которую вы видите впервые. Документация, которую вы видите впервые.