Правила для apps/docs/content/updates/<дата>.md, apps/docs/data/releases.json
и packages/cli/src/data/changelog.json. Нарушение пунктов 1–2 ломает
рендер страницы обновлений — это не стилистика.
Обновления хранятся по одному файлу на дату:
apps/docs/content/updates/<YYYY-MM-DD>.md с YAML-frontmatter и markdown-телом:
---
date: "2026-05-20"
title: "Список тредов"
---
Был добавлен новый метод:
- [Список тредов](GET /threads)
С помощью этого метода вы можете ...apps/docs/lib/updates-parser.ts (loadUpdates) читает всю директорию через
gray-matter: date и title берутся из frontmatter, тело — markdown.
Маркеров <!-- update: --> больше нет (это старый формат до миграции на
per-date файлы).
Поэтому:
- Один файл на дату. Имя файла = дата (
2026-05-20.md). Если запись с этой датой уже есть — дописывай в неё, не создавай второй файл. title— в frontmatter, не##в теле. Заголовок рендерится крупно с датой автоматически. В теле начинай сразу с параграфа/списка.##в теле станут сырыми подзаголовками внутри записи.- Несколько логически разных изменений на одну дату — объедини под одним
title, раздели параграфами и списками. Пример:Поле inviter_id, nullable-уточнения и chat_id в вебхуках.
apps/docs/content/updates.mdx — это обложка страницы /updates
(frontmatter + <ProductUpdatesLink />), записей она не содержит.
Страница /updates группирует записи по сезонам (🌷 Весна / ☀️ Лето /
🍁 Осень / ❄️ Зима), показывает последние сезоны и пагинацию; есть
посезонные страницы /updates/season/<slug> и одиночные /updates/<дата>.
Логика сезонов — apps/docs/lib/seasons.ts. Для формата записи это
прозрачно: пишешь файл на дату, сезон вычисляется автоматически.
Заголовки ## Сотрудник, ## Реакция на сообщение и т.п. в
apps/docs/content/api/models.mdx получают id через
apps/docs/lib/utils/transliterate.ts → toSlug()
(transliterate(text).toLowerCase() → пробелы в - → выкинуть всё, кроме
[a-z0-9-]). Кириллица в anchor (/api/models#сотрудник) не работает.
Частые модели: Сотрудник→sotrudnik, Чат→chat,
Сообщение→soobschenie, Тред→tred,
Реакция на сообщение→reaktsiya-na-soobschenie,
Напоминание→napominanie, Тег→teg.
Источник истины — атрибуты href в <Card> блоках в models.mdx
(там уже готовые правильные slug'и). Копировать оттуда, не вычислять руками.
Новый метод — сначала список методов, потом пояснение:
---
date: "YYYY-MM-DD"
title: "Заголовок"
---
Был добавлен новый метод:
- [Название метода](METHOD /path)
С помощью этого метода вы можете ...Обновлённый метод — сначала что изменилось, потом список:
---
date: "YYYY-MM-DD"
title: "Заголовок"
---
{Что изменилось, какие поля добавлены.}
Был обновлён следующий метод:
- [Название метода](METHOD /path)title— краткое название фичи, не «Добавлен метод...».- Множественное число:
Были добавлены новые методы:/Были обновлены следующие методы:. - Не-API обновления (документация, инструменты) — свободный формат без ссылок на методы.
[Текст](METHOD /path) автоматически рендерит цветной бейдж метода
(GET, POST, …) слева от текста. Если в текст ссылки положить
`GET /messages/{id}` — получится «GET GET /messages/{id}» (бейдж +
дублирующий код).
- Правильно:
[Информация о сообщении](GET /messages/{id}) - Неправильно:
[`GET /messages/{id}`](GET /messages/{id})
Допустимые методы в ссылках: GET, POST, PUT, DELETE.
5. Поведенческие нюансы и технические подробности — в гайд / на страницу метода, не в записи обновления
Запись обновления (content/updates/<дата>.md) — короткая сводка «что
изменилось», в стиле пресс-релиза. В неё не попадают:
- Имена параметров и полей — они уже видны на странице метода
(
/api/<resource>/<op>), которая открывается по ссылке[Название метода](METHOD /path)в этом же блоке. - Тип пагинации, сортировка, scoping — это контракт метода, отрисовывается в его описании и таблице параметров.
- Edge-case'ы и переходные оговорки (например, «для старых записей
придёт
null, пока не истечёт TTL»). Их место — в соответствующем гайде (apps/docs/content/guides/*.mdx), обычно в<Info>/<Warning>рядом со схемой.
В записи обновления остаются: один-два коротких предложения «что появилось + для чего», список ссылок на методы, и (если поведенческий нюанс правда важен) одна ссылка с якорем в гайд:
... добавлено поле `chat_id` ... Подробнее — в разделе
[Заполнение формы](/guides/webhook#zapolnenie-formy).Якорь строится через toSlug (см. правило 2).
Постоянная документация не должна содержать «до 4 мая 2026», «после
релиза 2.0.6» — через полгода такая привязка вводит в заблуждение.
Использовать обобщённо: «до выкатки этого изменения», «для форм, открытых
до изменения». Конкретная дата уже привязана к имени файла обновления
(content/updates/<дата>.md) и к версии в releases.json.
Сложившаяся конвенция — однопредложные описания без терминальной точки. Если описание многопредложное — внутри уже есть точки-разделители, тогда терминальная точка обязательна (иначе последнее предложение читается как обрыв). Лучший фолбэк — сократить до одного предложения.
Порядок блоков релизов и бейджей пакетов на странице обновлений
фиксирован: n8n → CLI → SDK → Generator. Сортировка сделана в
компоненте UpdatesList (apps/docs/components/api/updates-list.tsx),
поэтому порядок записей в data/releases.json влияния не имеет — но
ради читаемости diff'ов лучше добавлять в том же порядке.
Изменения без эффекта на пользователя пакета не пишутся нигде: ни в
apps/docs/content/updates/<дата>.md, ни в apps/docs/data/releases.json,
ни в integrations/<pkg>/CHANGELOG.md, ни в
packages/cli/src/data/changelog.json. Сюда относятся:
- Dev-only: prebuild-скрипты для локальных E2E, чистка dev-артефактов, фиксы CI/линтеров, перестановки в репо.
- Технические правки бэкенда, незаметные интегратору: ужесточение внутренних валидаций без изменения контракта (новый валидатор отвергает ввод, который и раньше «молча» приводил к сломанному поведению), смена внутренней реализации без новых полей/параметров/кодов ошибок, performance-тюнинг.
Changelog — история того, что заметит пользователь, скачавший пакет; всё остальное там шум, история живёт в git. Контрольный вопрос перед добавлением записи: «Заметит ли это пользователь, который скачал пакет / интегрировался с API?» Если ответ — «нет, разве что у него уже была сломанная интеграция» — не добавлять. Уже опубликованную такую запись не вычищаем отдельным релизом; правило — для будущих записей.
Текст записи обновления — максимально короткий: новое поле / новое
значение / новый метод и для чего оно. НЕ писать «Раньше запрос …
молча создавал …», НЕ писать «Изменение обратно совместимо: интеграции,
не передающие …, продолжают работать». Прежнее поведение и оговорки
совместимости — шум для канала «что нового». Один-два коротких
предложения: что добавлено + назначение. Если совместимость реально
неочевидна и важна — это поведенческий нюанс → в гайд (правило #5), не в
записи обновления. Та же установка на краткость — у @doc полей в
typespec.tsp (см. docs-conventions → TypeSpec
gotchas).
Одна и та же фича описывается независимыми текстами в нескольких местах — между ними нет автогенерации, рассинхрон случается легко. При правке формулировки (терминология, краткость, нейтральный голос) обязательно пройтись по всем местам, где это изменение упомянуто:
packages/spec/typespec.tsp—@docоперации (длинная версия, рендерится на странице метода).packages/spec/overlay.en.yaml— английская версия того же@doc(docs-conventions → TypeSpec gotchas: «EN overlay symmetry»).apps/docs/content/updates/<дата>.md— пресс-релиз для пользователя.apps/docs/data/releases.json— короткие записи по каждому пакету, рендерятся блоками рядом с записью обновления.integrations/n8n/CHANGELOG.md— английский changelog n8n-пакета, едет в npm-тарбол.packages/cli/src/data/changelog.json— источникpackages/cli/CHANGELOG.md.packages/spec/workflows.ts—notes/stepsworkflow'ов, если скилл затрагивает этот метод.
Если переписал длинное описание в @doc — короткие сводки в changelog'ах
и releases.json обычно тоже устарели: проверь, что в них нет тех же
старых терминов, длинных перечислений параметров и аудитории. Краткость
changelog-записей не освобождает их от правил терминологии
(docs-conventions → «Используй уже существующую
в spec лексику»).
Прежде чем поднимать версию пакета или заводить новый файл обновления
content/updates/<дата>.md, проверить публикацию: npm view @pachca/cli version, npm view n8n-nodes-pachca version, git tag --list 'v*' /
'n8n-v*'. Если верхняя запись в changelog/releases новее
опубликованного — релиз ещё не выпущен: новое изменение вкладывается
в эту pending-запись (дату при необходимости сдвинуть на дату
изменения), новая версия НЕ создаётся. То же для обновлений: если файл за
прошлую дату ещё не выпущен (тот же pending-релиз) — дописать в него и при
необходимости переименовать на дату релиза (правило #1), а не плодить
второй файл-дату. Инцидент 2026-05-16: создал CLI 2026.5.3 при
неопубликованном 2026.5.2 (npm latest 2026.5.1) — свернул в pending
2026.5.2; запись updates за 2026-05-15 слил в 2026-05-16. Полные правила
версий и публикации — docs/releases.md; процесс аудита —
API-аудит §4a.
См. также: API-аудит (когда и какие пакеты бампить — §4a), CONTRIBUTING.