Шаблон PR
и формы issue

§1API First: сначала договорились

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

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

§2Форма предложения изменить API

Файл .github/ISSUE_TEMPLATE/api_change.yml описывает форму, которую GitHub показывает вместо пустого поля ввода.

name: Предложение изменить API
description: Новая операция, поле, параметр или изменение поведения существующей операции
title: "[API] "
labels: ["api-change"]
body:
  - type: markdown
    attributes:
      value: |
        Контракт сначала обсуждается, потом реализуется (API First).
        Прочитайте docs/API_STYLE_GUIDE.md и docs/VERSIONING.md перед заполнением.

  - type: dropdown          # что предлагается: операция / поле / поведение / удаление
  - type: input             # операция: метод и путь
  - type: textarea          # какую задачу клиента это решает
  - type: textarea          # предлагаемый контракт
  - type: checkboxes        # совместимость проверена по docs/VERSIONING.md

Обратите внимание на подпись к третьему полю: «Опишите ситуацию, а не решение». Эта подпись переводит разговор с предложенного решения на задачу: вместо «добавьте поле priority» автор пишет «нам нужно показывать срочные обращения сверху». У такой формулировки может найтись другое, более удачное решение.

§3Почему форма, а не пустое поле

Свободный текст в issue гибче, но недостающие сведения приходится выяснять в переписке, по одному вопросу за раз.

В проекте три формы: предложение изменить API, сообщение об ошибке и проблема с документацией. Плюс файл config.yml, который убирает возможность создать issue без формы и добавляет ссылку на приватное сообщение об уязвимости — об этом в главе 7.2.

§4Шаблон pull request

Файл .github/PULL_REQUEST_TEMPLATE.md подставляется в описание каждого нового изменения. Первый вопрос в нём — о совместимости.

## Тип изменения

- [ ] совместимое изменение контракта (MINOR): новая операция, необязательный параметр,
      новое поле ответа
- [ ] исправление без изменения контракта (PATCH)
- [ ] **breaking change** (MAJOR): удаление, переименование, смена типа,
      новое обязательное поле
- [ ] только документация

Автор обязан выбрать один пункт, и это заставляет его сделать вывод о совместимости до того, как о ней скажет oasdiff. Если отметка автора расходится с выводом сборки, это означает одно из двух: автор неверно оценил своё изменение или политика совместимости описана неточно.

## Изменения контракта

| Операция или схема | Что изменилось |
|---|---|
| PATCH /api/v1/tickets/{ticket_id} | добавлен приём If-Match, ответ 412 |

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

§5Чек-лист проверок

## Проверки

- [ ] контракт выгружен: `python scripts/export_openapi.py`
- [ ] тесты проходят: `pytest`
- [ ] Spectral без замечаний
- [ ] изменение записано в `CHANGELOG.md`, раздел `[Unreleased]`
- [ ] у новых ответов с ошибкой есть страница вида проблемы в `scripts/build_docs.py`
- [ ] устаревающие элементы помечены `deprecated: true`, указаны замена и дата отключения
- [ ] для архитектурного решения добавлен ADR в `docs/adr/`

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

Четыре последних пункта сборка проверить не может:

§6Раздел «Для потребителей API»

## Для потребителей API

<!-- Что клиентам нужно сделать после выпуска. Если ничего — напишите «ничего». -->

Этот раздел требует от автора оценить изменение со стороны клиента API и сформулировать вывод словами.

Ответ «ничего» здесь допустим и встречается чаще всего; важно, что он написан, — значит, вопрос задавали. Если же ответ не «ничего», его текст переносят в CHANGELOG.md: там нужна такая же формулировка.

§7Как это выглядит вживую

Это изменение — демонстрационное: в нём поле updated_at переименовано в modified_at. В шаблоне автор честно отметил тип «breaking change» и в разделе «Для потребителей API» написал, что клиенты, читающие updated_at, перестанут получать значение. Изменение оставлено незакрытым: по нему видно и заполненный шаблон, и красную задачу breaking-changes рядом.

§8Как делают другие