01 / Revue de contrat
Nommez correctement la référence et le candidat
La référence est le contrat que les consommateurs existants utilisent déjà ; le candidat est le remplaçant proposé. Cette direction est importante car la suppression d’une opération ou la réduction d’une valeur acceptée a un effet de compatibilité différent de celui de l’ajout d’une.
Conserver les versions sources disponibles lors de la révision. Une correspondance de règle constitue une preuve d’une décision de publication et ne remplace pas la compréhension du flux de travail du consommateur concerné.
02 / Revue de contrat
Séparer les ruptures probables des changements dépendants du contexte
Examinez d’abord les éléments du contrat supprimés ou nouvellement requis, puis examinez les modifications dont l’effet dépend du comportement du consommateur ou de la sémantique d’exécution. Les ajouts compatibles méritent toujours d’être examinés en cas de comportement non documenté ou de validation personnalisée.
La comparaison décrit le contrat qu’elle peut analyser. Le comportement d’exécution, la mise en œuvre du serveur et les attentes non documentées restent en dehors de cette preuve.
- Commencez avec les chemins, opérations, paramètres, propriétés et valeurs d’énumération supprimés.
- Examiner les nouvelles exigences et les types plus restreints.
- Traitez le comportement sémantique comme une limite de révision humaine.
03 / Revue de contrat
Échec d’une tâche CI uniquement en cas de modifications incompatibles
Avec Pro sur Windows, exécutez diff-anything --cli --mode api --fail-on breaking ou définissez failOn : Break pour un cas dans un manifeste par lots. Les schémas identiques ou équivalents réussissent, les modifications ininterrompues sont autorisées et la tâche échoue en cas de modifications incompatibles et de modifications que les règles n’ont pas pu classer. Les sorties JUnit et SARIF répertorient chaque résultat avec son code de règle, tel que API001 pour une opération supprimée.
Les règles sont heuristiques : $ref est comparé tel qu’écrit plutôt que résolu, les schémas de requête et de réponse sont traités de la même manière, et certaines modifications incompatibles ne sont pas classées, comme une entrée de composants supprimée, un paramètre renommé ou déplacé, ou des propriétés supplémentaires ajoutées : false. Considérez un contrôle de réussite comme une première porte, et non comme une preuve de compatibilité, et conservez la même direction de base localement et dans CI.
