Репозиторий API содержит не только код. Шаблоны pull request, формы issue, владельцы кода, политика безопасности и журнал изменений есть у всех крупных проектов, но каждая компания устраивает их по-своему.
На следующих слайдах у каждого файла есть цитата из документации GitHub или стандарта в оригинале, перевод и настоящие файлы компаний. Полный список с доказательствами лежит в учебном проекте: docs/STANDARDS.md.
Правила компании обязательны только внутри этой компании. Для учебного проекта выбрано подходящее, и каждый выбор записан вместе с источником.
96Шаблон pull request: что проверить до слияния
Шаблон подставляется в описание каждого нового pull request. Автору он напоминает, что проверить, а ревьюеру показывает, где искать ответ.
To store your file in a hidden directory, name the pull request template .github/pull_request_template.md.
Перевод: чтобы хранить файл в скрытой папке, назовите шаблон pull request .github/pull_request_template.md.
В команде вместо имени указывают группу, например @org/api-reviewers. У Azure ↗ свои владельцы у спецификации каждого сервиса. Kubernetes использует другую систему: файлы OWNERS в папках читает бот Prow.
локальный запуск oasdiff: в ревизии поле title переименовано в subject
$ oasdiff breaking base.yaml revision.yaml --fail-on ERR
4 changes: 4 error, 0 warning, 0 info
error [response-required-property-removed] at /specs/revision.yaml
in API GET /api/v1/tickets
removed the required property `items/items/title` from the response with the `200` status
error [response-required-property-removed] at /specs/revision.yaml
in API POST /api/v1/tickets
removed the required property `title` from the response with the `201` status
# ещё две такие же ошибки: GET и PATCH /api/v1/tickets/{ticket_id}
github.com · pull request №6СКРИНШОТ · 16.09.2026
Прогон на учебном PR №6 (updated_at → modified_at): contract прошёл, breaking-changes упал, 5 аннотаций oasdiff — по одной на каждую операцию с полем в ответе. Клик — увеличить.
Тесты в этом PR проходят: переименование согласовано во всём коде. Остановил слияние только oasdiff, а защита ветки main требует обе проверки. Открыть прогон ↗.
102Адрес в поле type должен открываться
Problem Details различает виды ошибок по адресу в поле type. Стандарт требует, чтобы по этому адресу была документация.
If the type URI is a locator (e.g., those with an "http" or "https" scheme), dereferencing it SHOULD provide human-readable documentation for the problem type (e.g., using HTML).
Перевод: если URI в поле type является адресом (например, со схемой http или https), то по нему SHOULD открываться понятная человеку документация о виде проблемы, например HTML-страница.
В версии 1.0.0 учебного проекта type указывал на example.edu, где страницы нет. В 1.1.0 скрипт scripts/build_docs.py собирает страницу для каждого кода ошибки, а workflow docs.yml публикует их на GitHub Pages вместе с ReDoc.
Опубликованная страница вида проблемы 412: что означает ошибка и что делать клиенту. Клик — увеличить.
103Правило без источника легко оспорить
В учебном проекте для каждого правила записано, откуда оно взято, насколько оно обязательно и как то же самое решили другие компании.
docs/STANDARDS.md (фрагмент)
## 9. Ограничение частоты запросов: 429 и Retry-After
**В проекте:** app/limits.py
**Источник:** RFC 6585, раздел 4, Standards Track.
> The response representations SHOULD include details
> explaining the condition, and MAY include a Retry-After
> header indicating how long to wait before making a new request.
Перевод: ответ SHOULD объяснять причину и MAY содержать
заголовок Retry-After ...
**Как это делают другие:** Zalando (правило 153), GitHub ...
Статус источника
Что означает
RFC, Standards Track
стандарт IETF
RFC, Informational
опубликованный документ IETF, но не стандарт
Internet-Draft
черновик: может измениться или истечь
Спецификация
OpenAPI, Fetch Standard, SemVer
Правила компании
обязательны только внутри этой компании
Статус указывается рядом с цитатой: RFC 8594 про Sunset — Informational, а черновик про Idempotency-Key истёк.