Beleid voor data-API-opbouwfunctie
Een set beleidsregels is van toepassing op Data API Builder met betrekking tot wijzigingen die fouten veroorzaken, meldingen, releases en versiebeheer.
Versiebeheer en releases
Een release in de context van Data API Builder verwijst naar elke gepubliceerde versie van de software, geïdentificeerd door de Major.Minor.Patch indeling. Deze releases zijn onderverdeeld in drie categorieën: stabiel, wijziging die fouten veroorzaakt en preview.
Stabiele releases
Een stabiele versie van Data API Builder is achterwaarts compatibel. Compatibel met eerdere versies betekent dat code die u schrijft die afhankelijk is van één versie van een Data API-opbouwfunctie, een nieuwere stabiele versie kan aannemen zonder dat codewijzigingen nodig zijn om de juistheid of bestaande functionaliteit te behouden.
Wijzigingen die fouten veroorzaken
Een belangrijke wijzigingsversie van Data API Builder is niet achterwaarts compatibel. Voor het aannemen van een wijzigingsversie die fouten veroorzaakt in bestaande clientcode, zijn mogelijk codewijzigingen vereist om ervoor te zorgen dat de client zich precies zo gedraagt als bij de vorige versie.
Versies van wijzigingen die fouten veroorzaken, worden aangekondigd via het artikel in de lijst met belangrijke wijzigingen en in de wijzigingsbeschrijving van een GitHub-release. Publicatie van een preview-/release-kandidaatversie gaat vooraf aan de wijzigingsversies die fouten veroorzaken, tenzij de wijzigingen kritieke beveiligings-, privacy- of juridische problemen oplossen. Hoewel eerdere versies van Data API Builder mogelijk beschikbaar blijven op de pagina GitHub-releases, raden we u aan een upgrade uit te voeren naar de nieuwste versie, die mogelijk oplossingen voor fouten bevat.
Preview-releases
Preview-releases van Data API Builder worden geïdentificeerd met het X.Y.Z-rc versiebeheerschema. Het -rc achtervoegsel geeft aan dat de build een 'releasekandidaat' is. Preview-versies worden gebruikt om feedback te verzamelen over nieuwe functies en andere wijzigingen.
Tenzij we van plan zijn om opzettelijk belangrijke wijzigingen aan te brengen ten opzichte van de laatste stabiele versie, publiceren we de volgende preview-versie met alles van de nieuwste stabiele release en nieuwe preview-functies. De volgende update van Data API Builder kan een onderbreking opleveren voor enkele van de nieuwe preview-functies die we tussen preview-versies hebben toegevoegd. Dit foutgedrag betekent dat u mogelijk uw code moet wijzigen om alles weer te laten werken.
Preview-versies zijn niet bedoeld voor langdurig gebruik of voor productiegebruik. Wanneer er een nieuwe stabiele of preview-versie beschikbaar komt, zijn oudere preview-versies mogelijk niet meer toegankelijk. Het is raadzaam om preview-versies alleen te gebruiken wanneer u actief aan nieuwe functies werkt en snel na de release klaar bent om over te schakelen naar een niet-preview-versie. Als sommige functies van een preview-versie zijn opgenomen in een nieuwe stabiele versie, worden de resterende preview-functies toegevoegd aan een nieuwe preview-versie die u kunt uitproberen.
Versiewijzigingstabel
Belangrijk
We kunnen een belangrijke wijziging introduceren in een secundaire release of patchversie wanneer de wijziging kritieke productfouten, juridische, beveiligings- of privacyproblemen oplost.
| Releasetype | Vorige versie | Nieuwe versie | Notities |
|---|---|---|---|
| Wijziging die fouten veroorzaakt | 1.Y.Z |
2.Y.Z |
Nieuwe functies en oplossingen voor fouten, samen met eventuele wijzigingen die fouten veroorzaken. |
| Stabiel | 1.1.Z |
1.2.Z |
Nieuwe functies en oplossingen voor fouten zonder belangrijke wijzigingen, tenzij de wijzigingen betrekking hebben op kritieke productfouten, juridische, beveiligings- of privacyproblemen. |
| Stabiel | 1.1.1 |
1.1.2 |
Opgeloste fouten zonder nieuwe functies of wijzigingen die fouten veroorzaken, tenzij de wijzigingen betrekking hebben op kritieke productfouten, juridische, beveiligings- of privacyproblemen. |
| Preview | X.Y.1-rc |
X.Y.2-rc |
Nieuwe preview-functies en oplossingen voor fouten. (Wijzigingen die fouten veroorzaken, worden opgenomen als de primaire versie wordt gestoten.) |
Wijzigingen die fouten veroorzaken
Om prioriteit te geven aan beveiliging, functies te verbeteren en codekwaliteit te behouden, kunnen nieuwe versies van onze software wijzigingen bevatten die fouten veroorzaken. Hoewel we ernaar streven om deze wijzigingen te minimaliseren door middel van zorgvuldige architecturale keuzes, kunnen ze nog steeds optreden. In dergelijke gevallen maken we er prioriteit van om ze aan te kondigen en mogelijke oplossingen te bieden.
Belangrijk
We kunnen wijzigingen aanbrengen zonder voorafgaande kennisgeving als de wijziging wordt beschouwd als niet-brekend, of als het een belangrijke wijziging is die wordt aangebracht om kritieke productfouten of juridische, beveiligings- of privacyproblemen op te lossen.
Wat is een wijziging die fouten veroorzaakt?
Een wijziging die fouten veroorzaakt, is een wijziging waarvoor u uw toepassing moet bijwerken om onderbrekingen te voorkomen. In data-API-opbouwfunctie kunnen belangrijke wijzigingen wijzigingen in REST API-contracten, het genereren van GraphQL-schema's en andere elementen zijn die van invloed zijn op de compatibiliteit en functionaliteit.
Voorbeelden van wijzigingen die fouten veroorzaken
De volgende voorbeelden zijn een niet-uitputtende lijst met belangrijke wijzigingen in data-API-opbouwfunctie:
- Wijzigingen in REST API-contracten
- Wijzigingen in het genereren van GraphQL-schema's
- Wijzigingen die van invloed zijn op compatibiliteit met eerdere versies
- API's of parameters verwijderen of de naam ervan wijzigen
- Wijzigingen in foutcodes
- Aanpassingen aan de functionaliteit voor machtigingsdefinities
- Toegestane parameters, aanvraagvelden of antwoordvelden verwijderen
- Verplichte parameters of aanvraagvelden zonder standaardwaarden toevoegen
- Wijzigingen in de beoogde API-eindpuntfunctionaliteit
Definitie van een vaste wijziging
Een niet-belangrijke wijziging verwijst naar een wijziging die in uw toepassing kan worden geïntegreerd zonder onderbrekingen te veroorzaken. Vaste wijzigingen worden doorgaans gecommuniceerd na de implementatie. Uw toepassing moet zijn ontworpen om deze wijzigingen zonder voorafgaande kennisgeving af te handelen.
Voorbeelden van niet-belangrijke wijzigingen
De volgende voorbeelden zijn een niet-uitputtende lijst met vaste wijzigingen in data-API-opbouwfunctie:
- Introductie van nieuwe eindpunten
- Toevoeging van methoden aan bestaande eindpunten
- Opname van nieuwe velden in antwoorden en aanvragen
- Aanpassingen in veldvolgorde binnen antwoorden
- Introductie van optionele aanvraagheaders
- Wijzigingen in gegevenslengte en antwoordgrootte
- Wijzigingen in foutberichten en codes
- Oplossingen voor HTTP-antwoordcodes
- Extra metagegevens in gegenereerde OpenAPI-documenten
Hoe communiceren we belangrijke wijzigingen?
We stellen het als prioriteit om u onmiddellijk te informeren over wijzigingen die fouten veroorzaken. U vindt meldingen over wijzigingen die fouten veroorzaken in de releaseopmerkingen van Data API Builder-releases op GitHub en in het artikel speciale lijst met belangrijke wijzigingen.
Lijst met wijzigingen die fouten veroorzaken
Belangrijke wijzigingen en buitengebruikstelling van functies worden in dit artikel aangekondigd.
- Vanaf nu zijn er geen wijzigingen die fouten veroorzaken