Политики для построителя API данных
Набор политик управляет построителем API данных, связанным с критическими изменениями, уведомлениями, выпусками и управлением версиями.
Управление версиями и выпуски
Выпуск в контексте построителя API данных относится к каждой опубликованной версии программного обеспечения, определенной по форматуMajor.Minor.Patch. Эти выпуски делятся на три категории: стабильные, критические изменения и предварительные версии.
Стабильные выпуски
Стабильная версия построителя API данных обратно совместима. Обратная совместимость подразумевает, что любой код, который использует одну версию построителя API данных, может принять более новую стабильную версию без необходимости внесения изменений в код для поддержания правильности или существующих функциональных возможностей.
Выпуски критических изменений
Версия построителя API данных с критическим изменением не совместима с обратной совместимостью. Для внедрения версии критического изменения в существующем клиентском коде может потребоваться изменение кода, чтобы убедиться, что клиент ведет себя точно так же, как и при нацеливание на предыдущую версию.
Версии критических изменений объявляются в статье со списком критических изменений и в описании изменений выпуска GitHub. Публикация предварительной или релиз-кандидатной версии предшествует критическим изменениям версий, если изменения не устраняют критические проблемы безопасности, конфиденциальности или юридические проблемы. Хотя предыдущие версии построителя API данных могут оставаться доступными на странице выпусков GitHub, рекомендуется выполнить обновление до последнего выпуска, который может включать исправления ошибок.
Предварительные выпуски
Предварительные выпуски построителя API данных идентифицируются со схемой X.Y.Z-rc управления версиями. Суффикс -rc указывает, что сборка является "кандидатом на выпуск". Предварительные выпуски используются для сбора отзывов о новых функциях и других изменениях.
Если мы не планируем вносить существенные изменения с последней стабильной версии, мы публикуем следующую предварительную версию со всеми компонентами, начиная с последнего стабильного выпуска и новых предварительных версий. Следующее обновление построителя API данных может нарушить некоторые из новых предварительных версий функций, добавленных между предварительными версиями. Это критическое поведение означает, что вам может потребоваться изменить код, чтобы все снова работало.
Предварительные версии не предназначены для долгосрочного или рабочего использования. Когда станет доступна новая стабильная или предварительная версия, более старые предварительные версии могут быть недоступны. Рекомендуется использовать предварительные версии только в том случае, если вы активно работаете над новыми функциями и готовы перейти на не предварительную версию вскоре после выпуска. Если некоторые функции из предварительной версии включены в новую стабильную версию, остальные функции предварительной версии добавляются в новую предварительную версию, чтобы вы опробовали ее.
Таблица изменений версий
Важно!
Мы можем внести критическое изменение в дополнительный выпуск или выпуск исправлений, если это изменение устраняет критические ошибки продукта, юридические вопросы, проблемы безопасности или конфиденциальности.
| Тип выпуска | Предыдущая версия | Новая версия | Примечания |
|---|---|---|---|
| Критическое изменение | 1.Y.Z |
2.Y.Z |
Новые функции и исправления ошибок, а также критические изменения. |
| объем стабилен | 1.1.Z |
1.2.Z |
Новые функции и исправления ошибок без критических изменений, если они не затрагивают критически важные ошибки продукта, юридические вопросы, проблемы безопасности или конфиденциальности. |
| объем стабилен | 1.1.1 |
1.1.2 |
Исправления ошибок без каких-либо новых функций или критических изменений, если только изменения не устраняют критические ошибки продукта, юридические вопросы, проблемы безопасности или конфиденциальности. |
| Предварительный просмотр | X.Y.1-rc |
X.Y.2-rc |
Новые предварительные версии функций и исправления ошибок. (Критические изменения включаются в случае изменения основной версии.) |
Критические изменения
Для определения приоритетов безопасности, улучшения функций и поддержания качества кода новые версии программного обеспечения могут включать критические изменения. Хотя мы стремимся свести к минимуму эти изменения с помощью тщательного выбора архитектуры, они по-прежнему могут произойти. В таких случаях мы рекомендуем объявить о них и предоставить возможные решения.
Важно!
Мы можем внести изменения без предварительного уведомления, если это изменение считается некритичным или если это критическое изменение, внесенное для устранения критических ошибок продукта или юридических проблем, проблем безопасности или конфиденциальности.
Что такое критическое изменение?
Критическое изменение — это изменение, которое требует обновления приложения, чтобы предотвратить сбои. В построителе API данных критические изменения могут включать изменения в контрактах REST API, GraphQL создание схемы и другие элементы, влияющие на совместимость и функциональность.
Примеры критических изменений
В следующих примерах приведен неисчерпаемый список критических изменений в построителе API данных:
- Изменения контракта REST API
- Изменения в создании схемы GraphQL
- Изменения, влияющие на обратную совместимость
- Удаление или переименование API или параметров
- Изменения кодов ошибок
- Корректировки функциональных возможностей определения разрешений
- Удаление допустимых параметров, полей запросов или ответов
- Добавление обязательных параметров или полей запроса без значений по умолчанию
- Изменения в предполагаемых функциональных возможностях конечной точки API
Определение неразрывного изменения
Неразрывное изменение относится к изменению, которое можно интегрировать в приложение без прерывания работы. Неразрывные изменения обычно передаются после реализации. Приложение должно обрабатывать эти изменения без предварительного уведомления.
Примеры некриминационных изменений
В следующих примерах приведен неисчерпаемый список неразрывных изменений в построителе API данных:
- Введение в новые конечные точки
- Добавление методов в существующие конечные точки
- Включение новых полей в ответы и запросы
- Корректировка порядка полей в ответах
- Общие сведения о необязательных заголовках запросов
- Изменения длины данных и размера ответа
- Изменения в сообщениях об ошибках и коды
- Исправления кодов http-ответов
- Дополнительные метаданные в созданных документах OpenAPI
Как мы сообщаем о критических изменениях?
Мы уделяем приоритетное внимание оперативному информированию вас о критических изменениях. Уведомления о критических изменениях можно найти в заметках о выпуске выпусков построителя API данных на сайте GitHub, а также в статье с выделенным списком критических изменений.
Список текущих критических изменений
В этой статье описаны критические изменения и прекращение поддержки функций.
- На данный момент нет критических изменений