Remarque
L’accès à cette page nécessite une autorisation. Vous pouvez essayer de vous connecter ou de modifier des répertoires.
L’accès à cette page nécessite une autorisation. Vous pouvez essayer de modifier des répertoires.
Un ensemble de stratégies régit le générateur d’API de données lié aux changements cassants, aux notifications, aux versions et au contrôle de version.
Contrôle de version et versions
A release in the context of Data API builder refers to every published version of the software, identified by the Major.Minor.Patch format. These releases fall into three categories: stable, breaking change, and preview.
Responsabilité des mises à jour de conteneur
Le conteneur du générateur d’API de données ne se met pas à jour automatiquement. Les clients sont chargés de surveiller les nouvelles versions, d’évaluer leur importance (y compris les mises à jour de sécurité) et de mettre à jour les conteneurs déployés en conséquence.
Keeping the container up to date is the customer’s responsibility.
Stable releases
A stable version of Data API builder is backwards compatible. La compatibilité descendante implique que tout code que vous écrivez qui s’appuie sur une version d’un générateur d’API de données peut adopter une version stable plus récente sans nécessiter de modifications de code pour maintenir l’exactitude ou les fonctionnalités existantes.
Versions de modification cassants
Une version de modification cassant du générateur d’API de données n’est pas rétrocompatible. L’adoption d’une version de modification cassante dans le code client existant peut nécessiter des modifications de code pour s’assurer que le client se comporte exactement comme il l’a fait lors du ciblage de la version précédente.
Les versions de modification cassants sont annoncées via l’article de liste des modifications cassant et dans la description des modifications d’une version GitHub. La publication d’une version préliminaire/candidate de publication précède les versions de modification cassants, sauf si les modifications corrigent la sécurité critique, la confidentialité ou les problèmes juridiques. Bien que les versions précédentes du générateur d’API de données restent disponibles sur la page des versions gitHub, nous vous recommandons de procéder à une mise à niveau vers la dernière version, ce qui peut inclure des correctifs de bogues.
Preview releases
Les versions préliminaires du Générateur d’API de données sont identifiées avec le X.Y.Z-rc schéma de contrôle de version. Le -rc suffixe indique que la build est un « candidat à la mise en production ». Les préversions sont utilisées pour recueillir des commentaires sur les nouvelles fonctionnalités et d’autres modifications.
Sauf si nous prévoyons d’apporter des modifications significatives à partir de la dernière version stable, nous publions la prochaine préversion avec tous les éléments de la dernière version stable et de nouvelles fonctionnalités en préversion. La prochaine mise à jour du générateur d’API de données peut interrompre certaines des nouvelles fonctionnalités d’aperçu que nous avons ajoutées entre les versions préliminaires. Ce comportement cassant signifie que vous devrez peut-être modifier votre code pour que les choses fonctionnent à nouveau.
Les versions en préversion ne sont pas destinées à une utilisation à long terme ou en production. Lorsqu’une nouvelle version stable ou préliminaire est disponible, les versions antérieures de préversion peuvent ne plus être accessibles. Il est préférable d’utiliser des versions préliminaires uniquement lorsque vous travaillez activement sur de nouvelles fonctionnalités et que vous êtes prêt à basculer vers une version non préliminaire peu après la publication. Si certaines fonctionnalités d’une préversion sont incluses dans une nouvelle version stable, les fonctionnalités d’aperçu restantes sont ajoutées à une nouvelle version d’évaluation pour vous permettre d’essayer.
Tableau des modifications de version
Important
Nous pouvons introduire une modification cassant d’une version mineure ou corrective lorsque la modification traite les bogues de produit critiques, les problèmes juridiques, de sécurité ou de confidentialité.
| Release type | Previous Version | New Version | Notes |
|---|---|---|---|
| Breaking Change | 1.Y.Z |
2.Y.Z |
Nouvelles fonctionnalités et correctifs de bogues, ainsi que les changements cassants. |
| Stable | 1.1.Z |
1.2.Z |
Nouvelles fonctionnalités et correctifs de bogues sans modifications cassants, sauf si les modifications traitent les bogues critiques des produits, les problèmes juridiques, de sécurité ou de confidentialité. |
| Stable | 1.1.1 |
1.1.2 |
Correctifs de bogues sans nouvelles fonctionnalités ni modifications cassants, sauf si les modifications résolvent les bogues de produit critiques, les problèmes juridiques, de sécurité ou de confidentialité. |
| Preview | X.Y.1-rc |
X.Y.2-rc |
Nouvelles fonctionnalités et correctifs de bogues en préversion. (Les modifications cassants sont incluses si la version principale est modifiée.) |
Breaking Changes
Pour hiérarchiser la sécurité, améliorer les fonctionnalités et maintenir la qualité du code, les nouvelles versions de notre logiciel peuvent inclure des modifications cassants. Bien que nous nous efforçons de réduire ces modifications par le biais de choix architecturaux prudents, elles peuvent toujours se produire. Dans de tels cas, nous faisons en sorte qu’il soit prioritaire de les annoncer et de fournir des solutions possibles.
Important
Nous pouvons apporter des modifications sans préavis si le changement est considéré comme non cassant ou s’il s’agit d’une modification cassant apportée pour résoudre les bogues critiques du produit ou les problèmes juridiques, de sécurité ou de confidentialité.
Qu’est-ce qu’un changement cassant ?
Une modification cassant est une modification qui vous oblige à mettre à jour votre application pour éviter les interruptions. Dans le générateur d’API de données, les changements cassants peuvent inclure des modifications apportées aux contrats API REST, à la génération de schéma GraphQL et à d’autres éléments qui affectent la compatibilité et les fonctionnalités.
Exemples de modifications cassants
The following examples are a nonexhaustive list of breaking changes to Data API builder:
- Modifications du contrat d’API REST
- Modifications dans la génération de schéma GraphQL
- Modifications affectant la compatibilité descendante
- Suppression ou changement de nom d’API ou de paramètres
- Modifications dans les codes d’erreur
- Ajustements de la fonctionnalité de définition d’autorisation
- Suppression des paramètres autorisés, des champs de requête ou des champs de réponse
- Ajout de paramètres obligatoires ou de champs de requête sans valeurs par défaut
- Modifications apportées à la fonctionnalité de point de terminaison d’API prévue
Définition d’une modification non cassante
A non-breaking change refers to a change that can be integrated into your application without causing disruption. Les modifications non cassantes sont généralement communiquées après l’implémentation. Votre application doit être conçue pour gérer ces modifications sans préavis préalable.
Exemples de modifications non cassants
The following examples are a nonexhaustive list of nonbreaking changes to Data API builder:
- Introduction des nouveaux points de terminaison
- Ajout de méthodes aux points de terminaison existants
- Incorporation de nouveaux champs dans les réponses et les demandes
- Ajustements de l’ordre des champs dans les réponses
- Introduction des en-têtes de requête facultatifs
- Modifications apportées à la longueur des données et à la taille de la réponse
- Modifications apportées aux messages d’erreur et aux codes
- Correctifs apportés aux codes de réponse HTTP
- Métadonnées supplémentaires dans les documents OpenAPI générés
Comment communiquer les changements cassants ?
Nous mettons la priorité à vous informer rapidement des changements cassants. Vous trouverez des notifications de modification cassants dans les notes de publication des versions du générateur d’API de données sur GitHub.
Liste de modifications cassant actuelle
Les changements cassants et les mises hors service sont annoncées dans cet article.
- À l’heure actuelle, il n’y a pas de changements cassants